Merge branch 'sanddown' into 'master'

Reconcile source installation and upgrade docs

See merge request gitlab-org/gitlab!55170

changelogs/unreleased/sanddown.yml

+---
+title: reconcile source installation and upgrade docs
+merge_request: 55170
+author: Jörg Behrmann @behrmann
+type: fixed

doc/development/architecture.md

@@ -322,7 +322,7 @@ Consul is a tool for service discovery and configuration. Consul is distributed,
 - Configuration:
   - [Omnibus](https://docs.gitlab.com/omnibus/settings/database.html#disabling-automatic-database-migration)
   - [Charts](https://docs.gitlab.com/charts/charts/gitlab/migrations/)
-  - [Source](../update/upgrading_from_source.md#14-install-libraries-migrations-etc)
+  - [Source](../update/upgrading_from_source.md#10-install-libraries-migrations-etc)
 - Layer: Core Service (Data)
 
 #### Elasticsearch
@@ -641,7 +641,7 @@ Redis is packaged to provide a place to store:
 
 - [Project page](https://github.com/docker/distribution/blob/master/README.md)
 - Configuration:
-  - [Omnibus](../update/upgrading_from_source.md#14-install-libraries-migrations-etc)
+  - [Omnibus](../update/upgrading_from_source.md#10-install-libraries-migrations-etc)
   - [Charts](https://docs.gitlab.com/charts/charts/registry/)
   - [Source](../administration/packages/container_registry.md#enable-the-container-registry)
   - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/registry.md)

doc/install/installation.md

@@ -570,7 +570,9 @@ Install the gems (if you want to use Kerberos for user authentication, omit
 `kerberos` in the `--without` option below):
 
 ```shell
-sudo -u git -H bundle install --deployment --without development test mysql aws kerberos
+sudo -u git -H bundle config set deployment 'true'
+sudo -u git -H bundle config set without 'development test mysql aws kerberos'
+sudo -u git -H bundle install
 ```
 
 ### Install GitLab Shell

doc/update/upgrading_from_ce_to_ee.md

@@ -63,7 +63,9 @@ sudo -u git -H git checkout EE_BRANCH
 ```shell
 cd /home/git/gitlab
 
-sudo -u git -H bundle install --deployment --without development test mysql aws kerberos
+sudo -u git -H bundle config set deployment 'true'
+sudo -u git -H bundle config set without 'development test mysql aws kerberos'
+sudo -u git -H bundle install
 
 # Optional: clean up old gems
 sudo -u git -H bundle clean

doc/update/upgrading_from_source.md

@@ -127,41 +127,30 @@ Git v2.28 is recommended.
 To check you are running the minimum required Git version, see
 [Git versions](../install/requirements.md#git-versions).
 
-In Debian or Ubuntu:
-
-```shell
-# Make sure Git is version 2.29.0 or higher
-git --version
+From GitLab 13.6, we recommend you use the [Git version provided by
+Gitaly](https://gitlab.com/gitlab-org/gitaly/-/issues/2729)
+that:
 
-# Remove packaged Git
-sudo apt-get remove git-core
+- Is always at the version required by GitLab.
+- May contain custom patches required for proper operation.
 
+```shell
 # Install dependencies
-sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev build-essential
-
-# Download and compile pcre2 from source
-curl --silent --show-error --location "https://ftp.pcre.org/pub/pcre/pcre2-10.33.tar.gz" --output pcre2.tar.gz
-tar -xzf pcre2.tar.gz
-cd pcre2-10.33
-chmod +x configure
-./configure --prefix=/usr --enable-jit
-make
-make install
-
-# Download and compile from source
-cd /tmp
-curl --remote-name --location --progress "https://www.kernel.org/pub/software/scm/git/git-2.29.0.tar.gz"
-echo 'fa08dc8424ef80c0f9bf307877f9e2e49f1a6049e873530d6747c2be770742ff  git-2.29.0.tar.gz' | shasum -a256 -c - && tar -xzf git-2.29.0.tar.gz
-cd git-2.29.0/
-./configure --with-libpcre
-make prefix=/usr/local all
+sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev libpcre2-dev build-essential
 
-# Install into /usr/local/bin
-sudo make prefix=/usr/local install
+# Clone the Gitaly repository
+git clone https://gitlab.com/gitlab-org/gitaly.git -b <X-Y-stable> /tmp/gitaly
 
-# You should edit config/gitlab.yml, change the git -> bin_path to /usr/local/bin/git
+# Compile and install Git
+cd /tmp/gitaly
+sudo make git GIT_PREFIX=/usr/local
 ```
 
+Replace `<X-Y-stable>` with the stable branch that matches the GitLab version you want to
+install. For example, if you want to install GitLab 13.6, use the branch name `13-6-stable`.
+
+Remember to set `git -> bin_path` to `/usr/local/bin/git` in `config/gitlab.yml`.
+
 ### 7. Update PostgreSQL
 
 WARNING:
@@ -180,8 +169,7 @@ To upgrade PostgreSQL, refer to its [documentation](https://www.postgresql.org/d
 cd /home/git/gitlab
 
 sudo -u git -H git fetch --all --prune
-sudo -u git -H git checkout -- db/structure.sql # local changes will be restored automatically
-sudo -u git -H git checkout -- locale
+sudo -u git -H git checkout -- Gemfile.lock db/structure.sql locale
 ```
 
 For GitLab Community Edition:
@@ -202,55 +190,7 @@ cd /home/git/gitlab
 sudo -u git -H git checkout BRANCH-ee
 ```
 
-### 9. Update GitLab Shell
-
-```shell
-cd /home/git/gitlab-shell
-
-sudo -u git -H git fetch --all --tags --prune
-sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION)
-sudo -u git -H make build
-```
-
-### 10. Update GitLab Workhorse
-
-Install and compile GitLab Workhorse.
-
-```shell
-cd /home/git/gitlab
-
-sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production
-```
-
-### 11. Update Gitaly
-
-#### Compile Gitaly
-
-```shell
-cd /home/git/gitaly
-sudo -u git -H git fetch --all --tags --prune
-sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION)
-sudo -u git -H make
-```
-
-### 12. Update GitLab Pages
-
-#### Only needed if you use GitLab Pages
-
-Install and compile GitLab Pages. GitLab Pages uses
-[GNU Make](https://www.gnu.org/software/make/).
-If you are not using Linux you may have to run `gmake` instead of
-`make` below.
-
-```shell
-cd /home/git/gitlab-pages
-
-sudo -u git -H git fetch --all --tags --prune
-sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
-sudo -u git -H make
-```
-
-### 13. Update configuration files
+### 9. Update configuration files
 
 #### New configuration options for `gitlab.yml`
 
@@ -323,12 +263,17 @@ For Ubuntu 16.04.1 LTS:
 sudo systemctl daemon-reload
 ```
 
-### 14. Install libraries, migrations, etc
+### 10. Install libraries, migrations, etc
 
 ```shell
 cd /home/git/gitlab
 
-sudo -u git -H bundle install --deployment --without development test mysql aws kerberos
+# If you haven't done so during installation or a previous upgrade already
+sudo -u git -H bundle config set deployment 'true'
+sudo -u git -H bundle config set without 'development test mysql aws kerberos'
+
+# Update gems
+sudo -u git -H bundle install
 
 # Optional: clean up old gems
 sudo -u git -H bundle clean
@@ -337,7 +282,6 @@ sudo -u git -H bundle clean
 sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production
 
 # Compile GetText PO files
-
 sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production
 
 # Update node dependencies and recompile assets
@@ -347,6 +291,54 @@ sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:c
 sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production
 ```
 
+### 11. Update GitLab Shell
+
+```shell
+cd /home/git/gitlab-shell
+
+sudo -u git -H git fetch --all --tags --prune
+sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION)
+sudo -u git -H make build
+```
+
+### 12. Update GitLab Workhorse
+
+Install and compile GitLab Workhorse.
+
+```shell
+cd /home/git/gitlab
+
+sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production
+```
+
+### 13. Update Gitaly
+
+#### Compile Gitaly
+
+```shell
+cd /home/git/gitaly
+sudo -u git -H git fetch --all --tags --prune
+sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION)
+sudo -u git -H make
+```
+
+### 14. Update GitLab Pages
+
+#### Only needed if you use GitLab Pages
+
+Install and compile GitLab Pages. GitLab Pages uses
+[GNU Make](https://www.gnu.org/software/make/).
+If you are not using Linux you may have to run `gmake` instead of
+`make` below.
+
+```shell
+cd /home/git/gitlab-pages
+
+sudo -u git -H git fetch --all --tags --prune
+sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
+sudo -u git -H make
+```
+
 ### 15. Start application
 
 ```shell