1 files changed, 90 insertions, 0 deletions
diff --git a/doc/administration/high_availability/gitaly.md b/doc/administration/high_availability/gitaly.md
new file mode 100644
index 00000000000..d44744f2af8
--- /dev/null
+++ b/doc/administration/high_availability/gitaly.md
@@ -0,0 +1,90 @@
+# Configuring Gitaly for Scaled and High Availability
+
+Gitaly does not yet support full high availability. However, Gitaly is quite
+stable and is in use on GitLab.com. Scaled and highly available GitLab environments
+should consider using Gitaly on a separate node. 
+
+See the [Gitaly HA Epic](https://gitlab.com/groups/gitlab-org/-/epics/289) to 
+track plans and progress toward high availability support. 
+
+This document is relevant for [Scaled Architecture](./README.md#scalable-architecture-examples)
+environments and [High Availability Architecture](./README.md#high-availability-architecture-examples). 
+
+## 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).
+
+Continue configuration of other components by going back to:
+
+- [Scaled Architectures](./README.md#scalable-architecture-examples)
+- [High Availability Architectures](./README.md#high-availability-architecture-examples)