relative_url.md 4.12 KB
Newer Older
1
# Install GitLab under a relative URL
2

3
NOTE: **Note:**
4 5 6 7
This document describes how to run GitLab under a relative URL for installations
from source. If you are using an Omnibus package,
[the steps are different][omnibus-rel]. Use this guide along with the
[installation guide](installation.md) if you are installing GitLab for the
8
first time.
9 10 11

---

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
12
While it is recommended to install GitLab on its own (sub)domain, sometimes
13 14 15
this is not possible due to a variety of reasons. In that case, GitLab can also
be installed under a relative URL, for example `https://example.com/gitlab`.

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
16 17
There is no limit to how deeply nested the relative URL can be. For example you
could serve GitLab under `/foo/bar/gitlab/git` without any issues.
18 19

Note that by changing the URL on an existing GitLab installation, all remote
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
20
URLs will change, so you'll have to manually edit them in any local repository
21 22 23 24 25 26 27
that points to your GitLab instance.

---

The TL;DR list of configuration files that you need to change in order to
serve GitLab under a relative URL is:

28
- `/home/git/gitlab/config/initializers/relative_url.rb`
29 30 31 32 33 34 35
- `/home/git/gitlab/config/gitlab.yml`
- `/home/git/gitlab/config/unicorn.rb`
- `/home/git/gitlab-shell/config.yml`
- `/etc/default/gitlab`

After all the changes you need to recompile the assets and [restart GitLab].

36
## Relative URL requirements
37 38 39 40 41 42 43 44 45

If you configure GitLab with a relative URL, the assets (JavaScript, CSS, fonts,
images, etc.) will need to be recompiled, which is a task which consumes a lot
of CPU and memory resources. To avoid out-of-memory errors, you should have at
least 2GB of RAM available on your system, while we recommend 4GB RAM, and 4 or
8 CPU cores.

See the [requirements](requirements.md) document for more information.

46
## Enable relative URL in GitLab
47

48
NOTE: **Note:**
49
Do not make any changes to your web server configuration file regarding
50
relative URL. The relative URL support is implemented by GitLab Workhorse.
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68

---

Before following the steps below to enable relative URL in GitLab, some
assumptions are made:

- GitLab is served under `/gitlab`
- The directory under which GitLab is installed is `/home/git/`

Make sure to follow all steps below:

1.  (Optional) If you run short on resources, you can temporarily free up some
    memory by shutting down the GitLab service with the following command:

    ```shell
    sudo service gitlab stop
    ```

69 70 71 72 73 74 75 76
1.  Create `/home/git/gitlab/config/initializers/relative_url.rb`

    ```shell
    cp /home/git/gitlab/config/initializers/relative_url.rb.sample \
       /home/git/gitlab/config/initializers/relative_url.rb
    ```

    and change the following line:
77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105

    ```ruby
    config.relative_url_root = "/gitlab"
    ```

1.  Edit `/home/git/gitlab/config/gitlab.yml` and uncomment/change the
    following line:

    ```yaml
    relative_url_root: /gitlab
    ```

1.  Edit `/home/git/gitlab/config/unicorn.rb` and uncomment/change the
    following line:

    ```ruby
    ENV['RAILS_RELATIVE_URL_ROOT'] = "/gitlab"
    ```

1.  Edit `/home/git/gitlab-shell/config.yml` and append the relative path to
    the following line:

    ```yaml
    gitlab_url: http://127.0.0.1/gitlab
    ```

1.  Make sure you have copied the supplied init script and the defaults file
    as stated in the [installation guide](installation.md#install-init-script).
    Then, edit `/etc/default/gitlab` and set in `gitlab_workhorse_options` the
106
    `-authBackend` setting to read like:
107 108 109 110 111

    ```shell
    -authBackend http://127.0.0.1:8080/gitlab
    ```

112 113 114 115
    **Note:**
    If you are using a custom init script, make sure to edit the above
    gitlab-workhorse setting as needed.

116 117
1. [Restart GitLab][] for the changes to take effect.

118
## Disable relative URL in GitLab
119

120 121 122 123 124 125
To disable the relative URL:

1.  Remove `/home/git/gitlab/config/initializers/relative_url.rb`

1.  Follow the same as above starting from 2. and set up the
    GitLab URL to one that doesn't contain a relative path.
126

127
[omnibus-rel]: http://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab "How to set up relative URL in Omnibus GitLab"
128
[restart gitlab]: ../administration/restart_gitlab.md#installations-from-source "How to restart GitLab"