Commit 10aa99a3 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch 'doc_relative_url' into 'master'

Add documentation on relative URL support

closes #12773

See merge request !2770
parents 17240f80 464cea7d
...@@ -52,17 +52,11 @@ module Gitlab ...@@ -52,17 +52,11 @@ module Gitlab
config.action_view.sanitized_allowed_protocols = %w(smb) config.action_view.sanitized_allowed_protocols = %w(smb)
# Relative url support # Relative URL support
# Uncomment and customize the last line to run in a non-root path # WARNING: We recommend using an FQDN to host GitLab in a root path instead
# WARNING: We recommend creating a FQDN to host GitLab in a root path instead of this. # of using a relative URL.
# Note that following settings need to be changed for this to work. # Documentation: http://doc.gitlab.com/ce/install/relative_url.html
# 1) In your application.rb file: config.relative_url_root = "/gitlab" # Uncomment and customize the following line to run in a non-root path
# 2) In your gitlab.yml file: relative_url_root: /gitlab
# 3) In your unicorn.rb: ENV['RAILS_RELATIVE_URL_ROOT'] = "/gitlab"
# 4) In ../gitlab-shell/config.yml: gitlab_url: "http://127.0.0.1/gitlab"
# 5) In lib/support/nginx/gitlab : do not use asset gzipping, remove block starting with "location ~ ^/(assets)/"
#
# To update the path, run: sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production
# #
# config.relative_url_root = "/gitlab" # config.relative_url_root = "/gitlab"
......
...@@ -38,8 +38,12 @@ production: &base ...@@ -38,8 +38,12 @@ production: &base
# Otherwise, ssh host will be set to the `host:` value above # Otherwise, ssh host will be set to the `host:` value above
# ssh_host: ssh.host_example.com # ssh_host: ssh.host_example.com
# WARNING: See config/application.rb under "Relative url support" for the list of # Relative URL support
# other files that need to be changed for relative url support # WARNING: We recommend using an FQDN to host GitLab in a root path instead
# of using a relative URL.
# Documentation: http://doc.gitlab.com/ce/install/relative_url.html
# Uncomment and customize the following line to run in a non-root path
#
# relative_url_root: /gitlab # relative_url_root: /gitlab
# Uncomment and customize if you can't use the default user to run GitLab (default: 'git') # Uncomment and customize if you can't use the default user to run GitLab (default: 'git')
......
...@@ -10,9 +10,12 @@ ...@@ -10,9 +10,12 @@
# Note: If you change this file in a Merge Request, please also create a # Note: If you change this file in a Merge Request, please also create a
# Merge Request on https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests # Merge Request on https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests
#
# WARNING: See config/application.rb under "Relative url support" for the list of # Relative URL support
# other files that need to be changed for relative url support # WARNING: We recommend using an FQDN to host GitLab in a root path instead
# of using a relative URL.
# Documentation: http://doc.gitlab.com/ce/install/relative_url.html
# Uncomment and customize the following line to run in a non-root path
# #
# ENV['RAILS_RELATIVE_URL_ROOT'] = "/gitlab" # ENV['RAILS_RELATIVE_URL_ROOT'] = "/gitlab"
......
...@@ -484,6 +484,11 @@ You can use `sudo service gitlab start` and `sudo service gitlab stop` to start ...@@ -484,6 +484,11 @@ You can use `sudo service gitlab start` and `sudo service gitlab stop` to start
## Advanced Setup Tips ## Advanced Setup Tips
### Relative URL support
See the [Relative URL documentation](relative_url.md) for more information on
how to configure GitLab with a relative URL.
### Using HTTPS ### Using HTTPS
To use GitLab with HTTPS: To use GitLab with HTTPS:
......
## Install GitLab under a relative URL
_**Note:**
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
first time._
---
While it is recommended to 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`.
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.
Note that by changing the URL on an existing GitLab installation, all remote
URLs will change, so you'll have to manually edit them in any local repository
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:
- `/home/git/gitlab/config/application.rb`
- `/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].
### Relative URL requirements
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.
### 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._
---
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
```
1. Edit `/home/git/gitlab/config/application.rb` and uncomment/change the
following line:
```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
`-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 above
gitlab-workhorse setting as needed.
1. After all the above changes recompile the assets. This is an important task
and will take some time to complete depending on the server resources:
```
cd /home/git/gitlab
sudo -u git -H bundle exec rake assets:clean assets:precompile RAILS_ENV=production
```
1. [Restart GitLab][] for the changes to take effect.
### Disable relative URL in GitLab
To disable the relative URL, follow the same steps as above and set up the
GitLab URL to one that doesn't contain a relative path.
[omnibus-rel]: http://doc.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab "How to setup relative URL in Omnibus GitLab"
[restart gitlab]: ../administration/restart_gitlab.md#installations-from-source "How to restart GitLab"
...@@ -34,11 +34,16 @@ sidekiq_pid_path="$pid_path/sidekiq.pid" ...@@ -34,11 +34,16 @@ sidekiq_pid_path="$pid_path/sidekiq.pid"
# /home/git/gitlab-workhorse . # /home/git/gitlab-workhorse .
gitlab_workhorse_dir=$(cd $app_root/../gitlab-workhorse && pwd) gitlab_workhorse_dir=$(cd $app_root/../gitlab-workhorse && pwd)
gitlab_workhorse_pid_path="$pid_path/gitlab-workhorse.pid" gitlab_workhorse_pid_path="$pid_path/gitlab-workhorse.pid"
# The -listenXxx settings determine where gitlab-workhorse # The -listenXxx settings determine where gitlab-workhorse
# listens for connections from NGINX. To listen on localhost:8181, write # listens for connections from the web server. By default it listens to a
# '-listenNetwork tcp -listenAddr localhost:8181'. # socket. To listen on TCP connections (needed by Apache) change to:
# The -authBackend setting tells gitlab-workhorse where it can reach # '-listenNetwork tcp -listenAddr 127.0.0.1:8181'
# Unicorn. #
# The -authBackend setting tells gitlab-workhorse where it can reach Unicorn.
# For relative URL support change to:
# '-authBackend http://127.0.0.1/8080/gitlab'
# Read more in http://doc.gitlab.com/ce/install/relative_url.html
gitlab_workhorse_options="-listenUmask 0 -listenNetwork unix -listenAddr $socket_path/gitlab-workhorse.socket -authBackend http://127.0.0.1:8080 -authSocket $socket_path/gitlab.socket -documentRoot $app_root/public" gitlab_workhorse_options="-listenUmask 0 -listenNetwork unix -listenAddr $socket_path/gitlab-workhorse.socket -authBackend http://127.0.0.1:8080 -authSocket $socket_path/gitlab.socket -documentRoot $app_root/public"
gitlab_workhorse_log="$app_root/log/gitlab-workhorse.log" gitlab_workhorse_log="$app_root/log/gitlab-workhorse.log"
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment