From 41a957591274895bc15848744c35ee28adea0682 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 9 Feb 2016 16:31:38 +0200 Subject: [PATCH 1/4] Add relative URL documentation --- doc/install/installation.md | 5 ++ doc/install/relative_url.md | 123 ++++++++++++++++++++++++++++++++++++ 2 files changed, 128 insertions(+) create mode 100644 doc/install/relative_url.md diff --git a/doc/install/installation.md b/doc/install/installation.md index 3eb9b1767c5..86d37d64edd 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -484,6 +484,11 @@ You can use `sudo service gitlab start` and `sudo service gitlab stop` to start ## Advanced Setup Tips +### Relative URL support + +See the [Relative URL documentation](relative_url.md) for more information on +how to set this up. + ### Using HTTPS To use GitLab with HTTPS: diff --git a/doc/install/relative_url.md b/doc/install/relative_url.md new file mode 100644 index 00000000000..e6d530e2729 --- /dev/null +++ b/doc/install/relative_url.md @@ -0,0 +1,123 @@ +## 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 in 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 as to how much 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 basically 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` to read like: + + ```shell + -authBackend http://127.0.0.1:8080/gitlab + ``` + +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 a 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" From b532109b97a7764aef808673a084da1731ed452d Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 9 Feb 2016 16:50:42 +0200 Subject: [PATCH 2/4] Edit configuration files for relative URL support [ci skip] --- config/application.rb | 15 ++++----------- config/gitlab.yml.example | 7 +++++-- config/unicorn.rb.example | 8 +++++--- lib/support/init.d/gitlab.default.example | 13 +++++++++---- 4 files changed, 23 insertions(+), 20 deletions(-) diff --git a/config/application.rb b/config/application.rb index d255ff0719f..17574d8c992 100644 --- a/config/application.rb +++ b/config/application.rb @@ -52,17 +52,10 @@ module Gitlab config.action_view.sanitized_allowed_protocols = %w(smb) - # Relative url support - # Uncomment and customize the last line to run in a non-root path - # WARNING: We recommend creating a FQDN to host GitLab in a root path instead of this. - # Note that following settings need to be changed for this to work. - # 1) In your application.rb file: config.relative_url_root = "/gitlab" - # 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 + # Relative URL support + # WARNING: We recommend using an FQDN to host GitLab in a root path instead of this. + # Documentation: http://doc.gitlab.com/ce/install/relative_url.html + # Uncomment and customize the following line to run in a non-root path # # config.relative_url_root = "/gitlab" diff --git a/config/gitlab.yml.example b/config/gitlab.yml.example index d6e2c9380a5..667e32dd671 100644 --- a/config/gitlab.yml.example +++ b/config/gitlab.yml.example @@ -38,8 +38,11 @@ production: &base # Otherwise, ssh host will be set to the `host:` value above # ssh_host: ssh.host_example.com - # WARNING: See config/application.rb under "Relative url support" for the list of - # other files that need to be changed for relative url support + # Relative URL support + # WARNING: We recommend using an FQDN to host GitLab in a root path instead of this. + # 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 # Uncomment and customize if you can't use the default user to run GitLab (default: 'git') diff --git a/config/unicorn.rb.example b/config/unicorn.rb.example index b937b092789..02b251f1847 100644 --- a/config/unicorn.rb.example +++ b/config/unicorn.rb.example @@ -10,9 +10,11 @@ # 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 -# -# WARNING: See config/application.rb under "Relative url support" for the list of -# other files that need to be changed for relative url support + +# Relative URL support +# WARNING: We recommend using an FQDN to host GitLab in a root path instead of this. +# 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" diff --git a/lib/support/init.d/gitlab.default.example b/lib/support/init.d/gitlab.default.example index 4e6e56ac2db..cc8617b72ca 100755 --- a/lib/support/init.d/gitlab.default.example +++ b/lib/support/init.d/gitlab.default.example @@ -34,11 +34,16 @@ sidekiq_pid_path="$pid_path/sidekiq.pid" # /home/git/gitlab-workhorse . gitlab_workhorse_dir=$(cd $app_root/../gitlab-workhorse && pwd) gitlab_workhorse_pid_path="$pid_path/gitlab-workhorse.pid" + # The -listenXxx settings determine where gitlab-workhorse -# listens for connections from NGINX. To listen on localhost:8181, write -# '-listenNetwork tcp -listenAddr localhost:8181'. -# The -authBackend setting tells gitlab-workhorse where it can reach -# Unicorn. +# listens for connections from the web server. By default it listens to a +# socket. To listen on TCP connections (needed by Apache) change to: +# '-listenNetwork tcp -listenAddr 127.0.0.1:8181' +# +# 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_log="$app_root/log/gitlab-workhorse.log" From f81495b1e1afeacedf7bc66b69e238e3db53010f Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 9 Feb 2016 17:04:41 +0200 Subject: [PATCH 3/4] Add note on using a custom init script [ci skip] --- doc/install/relative_url.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/install/relative_url.md b/doc/install/relative_url.md index e6d530e2729..24dde42b310 100644 --- a/doc/install/relative_url.md +++ b/doc/install/relative_url.md @@ -98,12 +98,16 @@ Make sure to follow all steps below: 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` to read like: + `-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. From 464cea7d4892e76bcb39f0a3eaf848369178293a Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Wed, 10 Feb 2016 12:43:19 +0200 Subject: [PATCH 4/4] Fix typos and grammar [ci skip] --- config/application.rb | 3 ++- config/gitlab.yml.example | 3 ++- config/unicorn.rb.example | 3 ++- doc/install/installation.md | 2 +- doc/install/relative_url.md | 15 +++++++-------- 5 files changed, 14 insertions(+), 12 deletions(-) diff --git a/config/application.rb b/config/application.rb index 17574d8c992..ece8b3ff342 100644 --- a/config/application.rb +++ b/config/application.rb @@ -53,7 +53,8 @@ module Gitlab config.action_view.sanitized_allowed_protocols = %w(smb) # Relative URL support - # WARNING: We recommend using an FQDN to host GitLab in a root path instead of this. + # 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 # diff --git a/config/gitlab.yml.example b/config/gitlab.yml.example index 667e32dd671..faf05ecd466 100644 --- a/config/gitlab.yml.example +++ b/config/gitlab.yml.example @@ -39,7 +39,8 @@ production: &base # ssh_host: ssh.host_example.com # Relative URL support - # WARNING: We recommend using an FQDN to host GitLab in a root path instead of this. + # 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 # diff --git a/config/unicorn.rb.example b/config/unicorn.rb.example index 02b251f1847..e5058cebce8 100644 --- a/config/unicorn.rb.example +++ b/config/unicorn.rb.example @@ -12,7 +12,8 @@ # Merge Request on https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests # Relative URL support -# WARNING: We recommend using an FQDN to host GitLab in a root path instead of this. +# 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 # diff --git a/doc/install/installation.md b/doc/install/installation.md index 86d37d64edd..0bfd33da057 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -487,7 +487,7 @@ You can use `sudo service gitlab start` and `sudo service gitlab stop` to start ### Relative URL support See the [Relative URL documentation](relative_url.md) for more information on -how to set this up. +how to configure GitLab with a relative URL. ### Using HTTPS diff --git a/doc/install/relative_url.md b/doc/install/relative_url.md index 24dde42b310..b341b6311c6 100644 --- a/doc/install/relative_url.md +++ b/doc/install/relative_url.md @@ -9,15 +9,15 @@ first time._ --- -While it is recommended to install GitLab in its own (sub)domain, sometimes +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 as to how much deeply nested the relative URL can be. For -example you could serve GitLab under `/foo/bar/gitlab/git` without any issues. +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 +URLs will change, so you'll have to manually edit them in any local repository that points to your GitLab instance. --- @@ -47,8 +47,7 @@ See the [requirements](requirements.md) document for more information. _**Note:** Do not make any changes to your web server configuration file regarding -relative URL. The relative URL support is basically implemented by GitLab -Workhorse._ +relative URL. The relative URL support is implemented by GitLab Workhorse._ --- @@ -109,7 +108,7 @@ Make sure to follow all steps below: 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. + and will take some time to complete depending on the server resources: ``` cd /home/git/gitlab @@ -121,7 +120,7 @@ Make sure to follow all steps below: ### Disable relative URL in GitLab To disable the relative URL, follow the same steps as above and set up the -GitLab URL to a one that doesn't contain a relative path. +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"