Combine Running Gitaly on its own server details

doc/administration/gitaly/index.md

@@ -53,6 +53,10 @@ But since 11.8 the indexer uses Gitaly for data access as well. NFS can still
 be leveraged for redudancy on block level of the Git data. But only has to
 be mounted on the Gitaly server.
 
+NOTE: **Note:** While Gitaly can be used as a replacement for NFS, we do not recommend
+using EFS as it may impact GitLab's performance. Please review the [relevant documentation](../high_availability/nfs.md#avoid-using-awss-elastic-file-system-efs)
+for more details.
+
 ### Network architecture
 
 -   gitlab-rails shards repositories into "repository storages"
@@ -73,18 +77,29 @@ be mounted on the Gitaly server.
 -   Gitaly servers must not be exposed to the public internet
 
 Gitaly network traffic is unencrypted by default, but supports
-[TLS](#tls-support). Authentication is done through a static token. For 
-security in depth, its recommended to use a firewall to restrict access 
-to your Gitaly server.
+[TLS](#tls-support). Authentication is done through a static token.
+
+NOTE: **Note:** Gitaly network traffic is unencrypted so we recommend a firewall to
+restrict access to your Gitaly server.
 
 Below we describe how to configure a Gitaly server at address
 `gitaly.internal:8075` with secret token `abc123secret`. We assume
 your GitLab installation has two repository storages, `default` and
 `storage1`.
 
+### Installation
+
+First install Gitaly using either Omnibus or from source.
+
+Omnibus: [Download/install](https://about.gitlab.com/installation) the Omnibus GitLab
+package you want using **steps 1 and 2** from the GitLab downloads page but
+**_do not_** provide the `EXTERNAL_URL=` value.
+
+Source: [Install Gitaly](../../install/installation.md#install-gitaly)
+
 ### Client side token configuration
 
-Start by configuring a token on the client side.
+Configure a token on the client side.
 
 Omnibus installations:
 
@@ -110,7 +125,7 @@ changes to be picked up.
 Next, on the Gitaly server, we need to configure storage paths, enable
 the network listener and configure the token.
 
-Note: if you want to reduce the risk of downtime when you enable
+NOTE: **Note:** if you want to reduce the risk of downtime when you enable
 authentication you can temporarily disable enforcement, see [the
 documentation on configuring Gitaly
 authentication](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/configuration/README.md#authentication)
@@ -122,12 +137,17 @@ the Gitaly server. The easiest way to accomplish this is to copy `/etc/gitlab/gi
 from an existing GitLab server to the Gitaly server. Without this shared secret,
 Git operations in GitLab will result in an API error.
 
-> **NOTE:** In most or all cases the storage paths below end in `/repositories` which is
+NOTE: **Note:** In most or all cases the storage paths below end in `/repositories` which is
 different than `path` in `git_data_dirs` of Omnibus installations. Check the
 directory layout on your Gitaly server to be sure.
 
 Omnibus installations:
 
+<!--
+updates to following example must also be made at
+https://gitlab.com/charts/gitlab/blob/master/doc/advanced/external-gitaly/external-omnibus-gitaly.md#configure-omnibus-gitlab
+-->
+
 ```ruby
 # /etc/gitlab/gitlab.rb
 
@@ -147,6 +167,7 @@ gitlab_rails['auto_migrate'] = false
 # Configure the gitlab-shell API callback URL. Without this, `git push` will
 # fail. This can be your 'front door' GitLab URL or an internal load
 # balancer.
+# Don't forget to copy `/etc/gitlab/gitlab-secrets.json` from web server to Gitaly server.
 gitlab_rails['internal_api_url'] = 'https://gitlab.example.com'
 
 # Make Gitaly accept connections on all network interfaces. You must use

doc/administration/high_availability/gitaly.md

@@ -12,77 +12,8 @@ environments and [High Availability Architecture](./README.md#high-availability-
 
 ## Running Gitaly on its own server
 
-Starting with GitLab 11.4, Gitaly is a replacement for NFS except
-when the [Elastic Search indexer](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer)
-is used.
-
-NOTE: **Note:** While Gitaly can be used as a replacement for NFS, we do not recommend using EFS as it may impact GitLab's performance. Please review the [relevant documentation](nfs.md#avoid-using-awss-elastic-file-system-efs) for more details.
-
-NOTE: **Note:** Gitaly network traffic is unencrypted so we recommend a firewall to
-restrict access to your Gitaly server.
-
-The steps below are the minimum necessary to configure a Gitaly server with
-Omnibus:
-
-1. SSH into the Gitaly server.
-1. [Download/install](https://about.gitlab.com/installation) the Omnibus GitLab
-   package you want using **steps 1 and 2** from the GitLab downloads page.
-     - Do not complete any other steps on the download page.
-
-1. Edit `/etc/gitlab/gitlab.rb` and add the contents:
-
-    Gitaly must trigger some callbacks to GitLab via GitLab Shell. As a result,
-    the GitLab Shell secret must be the same between the other GitLab servers and
-    the Gitaly server. The easiest way to accomplish this is to copy `/etc/gitlab/gitlab-secrets.json`
-    from an existing GitLab server to the Gitaly server. Without this shared secret,
-    Git operations in GitLab will result in an API error.
-
-    > **NOTE:** In most or all cases the storage paths below end in `repositories` which is
-    different than `path` in `git_data_dirs` of Omnibus installations. Check the
-    directory layout on your Gitaly server to be sure.
-
-    ```ruby
-    # Enable Gitaly
-    gitaly['enable'] = true
-
-    ## Disable all other services
-    sidekiq['enable'] = false
-    gitlab_workhorse['enable'] = false
-    unicorn['enable'] = false
-    postgresql['enable'] = false
-    nginx['enable'] = false
-    prometheus['enable'] = false
-    alertmanager['enable'] = false
-    pgbouncer_exporter['enable'] = false
-    redis_exporter['enable'] = false
-    gitlab_monitor['enable'] = false
-
-    # Prevent database connections during 'gitlab-ctl reconfigure'
-    gitlab_rails['rake_cache_clear'] = false
-    gitlab_rails['auto_migrate'] = false
-
-    # Configure the gitlab-shell API callback URL. Without this, `git push` will
-    # fail. This can be your 'front door' GitLab URL or an internal load
-    # balancer.
-    gitlab_rails['internal_api_url'] = 'https://gitlab.example.com'
-
-    # Make Gitaly accept connections on all network interfaces. You must use
-    # firewalls to restrict access to this address/port.
-    gitaly['listen_addr'] = "0.0.0.0:8075"
-    gitaly['auth_token'] = 'abc123secret'
-
-    gitaly['storage'] = [
-      { 'name' => 'default', 'path' => '/mnt/gitlab/default/repositories' },
-      { 'name' => 'storage1', 'path' => '/mnt/gitlab/storage1/repositories' },
-    ]
-
-    # To use tls for gitaly you need to add
-    gitaly['tls_listen_addr'] = "0.0.0.0:9999"
-    gitaly['certificate_path'] = "path/to/cert.pem"
-    gitaly['key_path'] = "path/to/key.pem"
-    ```
-
-Again, reconfigure (Omnibus) or restart (source).
+See [Running Gitaly on its own server](../gitaly/index.md#running-gitaly-on-its-own-server)
+in Gitaly documentation.
 
 Continue configuration of other components by going back to: