From 6e4e1050d9dba2b7b2523fdd1768823ab85feef4 Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Thu, 20 Aug 2020 18:42:06 +0000 Subject: Add latest changes from gitlab-org/gitlab@13-3-stable-ee --- doc/install/installation.md | 85 ++++++++++++++++++++++++++++----------------- 1 file changed, 54 insertions(+), 31 deletions(-) (limited to 'doc/install/installation.md') diff --git a/doc/install/installation.md b/doc/install/installation.md index 8b285e0c9f1..7216f750624 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -28,12 +28,12 @@ following the Since an installation from source is a lot of work and error prone we strongly recommend the fast and reliable [Omnibus package installation](https://about.gitlab.com/install/) (deb/rpm). One reason the Omnibus package is more reliable is its use of runit to restart any of the GitLab processes in case one crashes. -On heavily used GitLab instances the memory usage of the Sidekiq background worker will grow over time. +On heavily used GitLab instances the memory usage of the Sidekiq background worker grows over time. Omnibus packages solve this by [letting the Sidekiq terminate gracefully](../administration/operations/sidekiq_memory_killer.md) if it uses too much memory. -After this termination runit will detect Sidekiq is not running and will start it. +After this termination runit detects Sidekiq is not running and starts it. Since installations from source don't use runit for process supervision, Sidekiq -can't be terminated and its memory usage will grow over time. +can't be terminated and its memory usage grows over time. ## Select a version to install @@ -44,7 +44,7 @@ If the highest number stable branch is unclear, check the [GitLab blog](https:// ## GitLab directory structure -This is the main directory structure you will end up with following the instructions +This is the main directory structure you end up with following the instructions of this page: ```plaintext @@ -99,7 +99,7 @@ apt-get install sudo -y ``` NOTE: **Note:** -During this installation, some files will need to be edited manually. If you are familiar with vim, set it as default editor with the commands below. If you are not familiar with vim, skip this and keep using the default editor. +During this installation, some files need to be edited manually. If you are familiar with vim, set it as default editor with the commands below. If you are not familiar with vim, skip this and keep using the default editor. ```shell # Install vim and set as default editor @@ -134,7 +134,7 @@ Make sure you have the right version of Git installed: # Install Git sudo apt-get install -y git-core -# Make sure Git is version 2.27.0 or higher (minimal supported version is 2.25.0) +# Make sure Git is version 2.24.0 or higher (recommended version is 2.28.0) git --version ``` @@ -181,9 +181,9 @@ sudo make install # Download and compile from source cd /tmp -curl --remote-name --location --progress https://www.kernel.org/pub/software/scm/git/git-2.27.0.tar.gz -echo '77ded85cbe42b1ffdc2578b460a1ef5d23bcbc6683eabcafbb0d394dffe2e787 git-2.27.0.tar.gz' | shasum -a256 -c - && tar -xzf git-2.27.0.tar.gz -cd git-2.27.0/ +curl --remote-name --location --progress https://www.kernel.org/pub/software/scm/git/git-2.28.0.tar.gz +echo 'f914c60a874d466c1e18467c864a910dd4ea22281ba6d4d58077cb0c3f115170 git-2.28.0.tar.gz' | shasum -a256 -c - && tar -xzf git-2.28.0.tar.gz +cd git-2.28.0/ ./configure --with-libpcre make prefix=/usr/local all @@ -200,7 +200,8 @@ needs to be installed. sudo apt-get install -y graphicsmagick ``` -**Note:** In order to receive mail notifications, make sure to install a mail server. By default, Debian is shipped with exim4 but this [has problems](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/12754) while Ubuntu does not ship with one. The recommended mail server is postfix and you can install it with: +NOTE: **Note:** +In order to receive mail notifications, make sure to install a mail server. By default, Debian is shipped with exim4 but this [has problems](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/12754) while Ubuntu does not ship with one. The recommended mail server is postfix and you can install it with: ```shell sudo apt-get install -y postfix @@ -219,8 +220,9 @@ sudo apt-get install -y libimage-exiftool-perl The Ruby interpreter is required to run GitLab. -**Note:** The current supported Ruby (MRI) version is 2.6.x. GitLab 12.2 - dropped support for Ruby 2.5.x. +NOTE: **Note:** +The current supported Ruby (MRI) version is 2.6.x. GitLab 12.2 +dropped support for Ruby 2.5.x. The use of Ruby version managers such as [RVM](https://rvm.io/), [rbenv](https://github.com/rbenv/rbenv) or [chruby](https://github.com/postmodern/chruby) with GitLab in production, frequently leads to hard to diagnose problems. Version managers @@ -284,7 +286,7 @@ requirements for these are: In many distros, the versions provided by the official package repositories are out of date, so -we'll need to install through the following commands: +we need to install through the following commands: ```shell # install node v12.x @@ -331,12 +333,18 @@ Starting from GitLab 12.1, only PostgreSQL is supported. Since GitLab 13.0, we r sudo -u postgres psql -d template1 -c "CREATE USER git CREATEDB;" ``` -1. Create the `pg_trgm` extension (required for GitLab 8.6+): +1. Create the `pg_trgm` extension: ```shell sudo -u postgres psql -d template1 -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;" ``` +1. Create the `btree_gist` extension (required for GitLab 13.1+): + + ```shell + sudo -u postgres psql -d template1 -c "CREATE EXTENSION IF NOT EXISTS btree_gist;" + ``` + 1. Create the GitLab production database and grant all privileges on the database: ```shell @@ -358,7 +366,25 @@ Starting from GitLab 12.1, only PostgreSQL is supported. Since GitLab 13.0, we r AND installed_version IS NOT NULL; ``` - If the extension is enabled this will produce the following output: + If the extension is enabled this produces the following output: + + ```plaintext + enabled + --------- + t + (1 row) + ``` + +1. Check if the `btree_gist` extension is enabled: + + ```sql + SELECT true AS enabled + FROM pg_available_extensions + WHERE name = 'btree_gist' + AND installed_version IS NOT NULL; + ``` + + If the extension is enabled this produces the following output: ```plaintext enabled @@ -436,7 +462,7 @@ Clone Enterprise Edition: ```shell # Clone GitLab repository -sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ee.git -b X-Y-stable gitlab +sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab.git -b X-Y-stable gitlab ``` Make sure to replace `X-Y-stable` with the stable branch that matches the @@ -496,9 +522,6 @@ sudo -u git -H cp config/puma.rb.example config/puma.rb # cores you have available. You can get that number via the `nproc` command. sudo -u git -H editor config/puma.rb -# Copy the example Rack attack config -sudo -u git -H cp config/initializers/rack_attack.rb.example config/initializers/rack_attack.rb - # Configure Git global settings for git user # 'autocrlf' is needed for the web editor sudo -u git -H git config --global core.autocrlf input @@ -541,7 +564,6 @@ sudo -u git cp config/database.yml.postgresql config/database.yml # adapter: postgresql # encoding: unicode # database: gitlabhq_production -# pool: 10 # sudo -u git -H editor config/database.yml @@ -591,12 +613,12 @@ NOTE: **Note:** If you want to use HTTPS, see [Using HTTPS](#using-https) for the additional steps. NOTE: **Note:** -Make sure your hostname can be resolved on the machine itself by either a proper DNS record or an additional line in `/etc/hosts` ("127.0.0.1 hostname"). This might be necessary, for example, if you set up GitLab behind a reverse proxy. If the hostname cannot be resolved, the final installation check will fail with `Check GitLab API access: FAILED. code: 401` and pushing commits will be rejected with `[remote rejected] master -> master (hook declined)`. +Make sure your hostname can be resolved on the machine itself by either a proper DNS record or an additional line in `/etc/hosts` ("127.0.0.1 hostname"). This might be necessary, for example, if you set up GitLab behind a reverse proxy. If the hostname cannot be resolved, the final installation check fails with `Check GitLab API access: FAILED. code: 401` and pushing commits are rejected with `[remote rejected] master -> master (hook declined)`. ### Install GitLab Workhorse GitLab-Workhorse uses [GNU Make](https://www.gnu.org/software/make/). The -following command-line will install GitLab-Workhorse in `/home/git/gitlab-workhorse` +following command-line installs GitLab-Workhorse in `/home/git/gitlab-workhorse` which is the recommended location. ```shell @@ -612,7 +634,7 @@ sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workh ### Install GitLab-Elasticsearch-indexer on Enterprise Edition GitLab-Elasticsearch-Indexer uses [GNU Make](https://www.gnu.org/software/make/). The -following command-line will install GitLab-Elasticsearch-Indexer in `/home/git/gitlab-elasticsearch-indexer` +following command-line installs GitLab-Elasticsearch-Indexer in `/home/git/gitlab-elasticsearch-indexer` which is the recommended location. ```shell @@ -625,15 +647,15 @@ You can specify a different Git repository by providing it as an extra parameter sudo -u git -H bundle exec rake "gitlab:indexer:install[/home/git/gitlab-elasticsearch-indexer,https://example.com/gitlab-elasticsearch-indexer.git]" RAILS_ENV=production ``` -The source code will first be fetched to the path specified by the first parameter. Then a binary will be built under its `bin` directory. -You will then need to update `gitlab.yml`'s `production -> elasticsearch -> indexer_path` setting to point to that binary. +The source code first is fetched to the path specified by the first parameter. Then a binary is built under its `bin` directory. +You then need to update `gitlab.yml`'s `production -> elasticsearch -> indexer_path` setting to point to that binary. NOTE: **Note:** Elasticsearch is a feature of GitLab Enterprise Edition and isn't included in GitLab Community Edition. ### Install GitLab Pages -GitLab Pages uses [GNU Make](https://www.gnu.org/software/make/). This step is optional and only needed if you wish to host static sites from within GitLab. The following commands will install GitLab Pages in `/home/git/gitlab-pages`. For additional setup steps, consult the [administration guide](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/administration/pages/source.md) for your version of GitLab as the GitLab Pages daemon can be run several different ways. +GitLab Pages uses [GNU Make](https://www.gnu.org/software/make/). This step is optional and only needed if you wish to host static sites from within GitLab. The following commands install GitLab Pages in `/home/git/gitlab-pages`. For additional setup steps, consult the [administration guide](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/administration/pages/source.md) for your version of GitLab as the GitLab Pages daemon can be run several different ways. ```shell cd /home/git @@ -712,7 +734,7 @@ Otherwise, your secrets are exposed if one of your backups is compromised. ### Install Init Script -Download the init script (will be `/etc/init.d/gitlab`): +Download the init script (is `/etc/init.d/gitlab`): ```shell sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab @@ -724,7 +746,7 @@ And if you are installing with a non-default folder or user copy and edit the de sudo cp lib/support/init.d/gitlab.default.example /etc/default/gitlab ``` -If you installed GitLab in another directory or as a user other than the default, you should change these settings in `/etc/default/gitlab`. Do not edit `/etc/init.d/gitlab` as it will be changed on upgrade. +If you installed GitLab in another directory or as a user other than the default, you should change these settings in `/etc/default/gitlab`. Do not edit `/etc/init.d/gitlab` as it is changed on upgrade. Make GitLab start on boot: @@ -812,7 +834,8 @@ If you intend to enable GitLab Pages, there is a separate NGINX config you need to use. Read all about the needed configuration at the [GitLab Pages administration guide](../administration/pages/index.md). -**Note:** If you want to use HTTPS, replace the `gitlab` NGINX config with `gitlab-ssl`. See [Using HTTPS](#using-https) for HTTPS configuration details. +NOTE: **Note:** +If you want to use HTTPS, replace the `gitlab` NGINX config with `gitlab-ssl`. See [Using HTTPS](#using-https) for HTTPS configuration details. ### Test Configuration @@ -920,7 +943,7 @@ See the [GitLab Runner section](https://about.gitlab.com/stages-devops-lifecycle ### Adding your Trusted Proxies If you are using a reverse proxy on a separate machine, you may want to add the -proxy to the trusted proxies list. Otherwise users will appear signed in from the +proxy to the trusted proxies list. Otherwise users appear signed in from the proxy's IP address. You can add trusted proxies in `config/gitlab.yml` by customizing the `trusted_proxies` @@ -992,7 +1015,7 @@ If you want to switch back to Unicorn, follow these steps: ### Using Sidekiq instead of Sidekiq Cluster As of GitLab 12.10, Source installations are using `bin/sidekiq-cluster` for managing Sidekiq processes. -Using Sidekiq directly will still be supported until 14.0. So if you're experiencing issues, please: +Using Sidekiq directly is still supported until 14.0. So if you're experiencing issues, please: 1. Edit the system `init.d` script to remove the `SIDEKIQ_WORKERS` flag. If you have `/etc/default/gitlab`, then you should edit it instead. 1. Restart GitLab. -- cgit v1.2.1