Install GitLab under a relative URL - Gitlabhq

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed
Status: Beta

[!warning] Configuring a relative URL for GitLab has known issues with Geo and testing limitations. If you are already using a relative URL and want to migrate to a subdomain, see the migration guide.

While you should install GitLab on its own (sub)domain, sometimes 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.

This document describes how to run GitLab under a relative URL for installations from source. Check the relative URL documentation for the Linux package or for GitLab chart to enable relative URLs if you are not installing from source.

Use this guide along with the installation guide if you are installing GitLab for the first time.

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.

Changing the URL on an existing GitLab installation, changes all remote URLs, so you have to manually edit them in any local repository that points to your GitLab instance.

The list of configuration files you must change to serve GitLab from a relative URL is:

/home/git/gitlab/config/initializers/relative_url.rb
/home/git/gitlab/config/gitlab.yml
/home/git/gitlab/config/puma.rb
/home/git/gitlab-shell/config.yml
/etc/default/gitlab

After all the changes, you must recompile the assets and restart GitLab.

Relative URL requirements

If you configure GitLab with a relative URL, the assets (including JavaScript, CSS, fonts, and images) must be recompiled, which can consume a lot of CPU and memory resources. To avoid out-of-memory errors, you should have at least 2 GB of RAM available on your computer. Ideally, you should have 4 GB RAM, and four or eight CPU cores.

See the requirements document for more information.

Enable relative URL in GitLab

[!note] Do not make any changes to your web server configuration file regarding relative URL. The relative URL support is implemented by GitLab Workhorse.

This process assumes:

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

To enable relative URLs in GitLab:

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
```

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:

ruby

config.relative_url_root = "/gitlab"

Edit /home/git/gitlab/config/gitlab.yml and uncomment/change the following line:
yaml
```
relative_url_root: /gitlab
```
Edit /home/git/gitlab/config/puma.rb and uncomment/change the following line:
ruby
```
ENV['RAILS_RELATIVE_URL_ROOT'] = "/gitlab"
```
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
```
Make sure you have copied either the supplied systemd services, or the init script and the defaults file, as stated in the installation guide. Then, edit /etc/default/gitlab and set in gitlab_workhorse_options the -authBackend setting to read like:
shell
```
-authBackend http://127.0.0.1:8080/gitlab
```
[!note] If you are using a custom init script, make sure to edit the previous GitLab Workhorse setting as needed.
Restart GitLab for the changes to take effect.

Disable relative URL in GitLab

To disable the relative URL:

Remove /home/git/gitlab/config/initializers/relative_url.rb
Follow the previous steps starting from 2. and set up the GitLab URL to one that doesn't contain a relative path.