From d791b1ef4d8b8a006c6aff438e4c74761a184c57 Mon Sep 17 00:00:00 2001
From: Jacob Vosmaer <jacob@gitlab.com>
Date: Fri, 17 Mar 2017 12:19:38 +0100
Subject: [PATCH] Add gitaly admin docs

---
 doc/administration/gitaly/index.md | 86 ++++++++++++++++++++++++++++++
 doc/install/installation.md        |  3 ++
 2 files changed, 89 insertions(+)
 create mode 100644 doc/administration/gitaly/index.md

diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md
new file mode 100644
index 00000000000..4542492e2da
--- /dev/null
+++ b/doc/administration/gitaly/index.md
@@ -0,0 +1,86 @@
+# Gitaly
+
+[Gitaly](https://gitlab.com/gitlab-org/gitlay) (introduced in GitLab
+9.0) is a service that provides high-level RPC access to Git
+repositories. As of GitLab 9.0 it is still an optional component with
+limited scope.
+
+GitLab components that access Git repositories (gitlab-rails,
+gitlab-shell, gitlab-workhorse) act as clients to Gitaly. End users do
+not have direct access to Gitaly.
+
+## Configuring Gitaly
+
+The Gitaly service itself is configured via environment variables.
+These variables are documented [in the gitaly
+repository](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/configuration/README.md).
+
+To change a Gitaly environment variable in Omnibus you can use
+`gitaly['env']` in `/etc/gitlab/gitlab.rb`. Changes will be applied
+when you run `gitlab-ctl reconfigure`.
+
+```ruby
+gitaly['env'] = {
+  'GITALY_MY_VARIABLE' => 'value'
+}
+```
+
+To change a Gitaly environment variable in installations from source
+you can edit `/home/git/gitaly/env`.
+
+```shell
+GITALY_MY_VARIABLE='value'
+```
+
+Changes to `/home/git/gitaly/env` are applied when you run `service
+gitlab restart`.
+
+## Configuring GitLab to not use Gitaly
+
+Gitaly is still an optional componennt in GitLab 9.0. This means you
+can choose to not use it.
+
+In Omnibus you can make the following change in
+`/etc/gitlab/gitlab.rb` and reconfigure. This will both disable the
+Gitaly service and configure the rest of GitLab not to use it.
+
+```ruby
+gitaly['enable'] = false
+```
+
+In source installations, edit `/home/git/gitlab/config/gitlab.yml` and
+make sure `socket_path` in the `gitaly` section is commented out. This
+does not disable the Gitaly service; it only prevents it from being
+used.
+
+Apply the change with `service gitlab restart`.
+
+```yaml
+  gitaly:
+    # socket_path: tmp/sockets/private/gitlay.socket
+```
+
+## Disabling or enabling the Gitaly service
+
+Be careful: if you disable Gitaly without instructing the rest of your
+GitLab installation not to use Gitaly, you may end up with errors
+because GitLab tries to access a service that is not running.
+
+To disable the Gitaly service in your Omnibus installation, add the
+following line to `/etc/gitlab/gitlab.rb`:
+
+```ruby
+gitaly['enable'] = false
+```
+
+When you run `gitlab-ctl reconfigure` the Gitaly service will be
+disabled.
+
+To disable the Gitaly service in an installation from source, add the
+following to `/etc/default/gitlab`:
+
+```shell
+gitaly_enabled=false
+```
+
+When you run `service gitlab restart` Gitaly will be disabled.
\ No newline at end of file
diff --git a/doc/install/installation.md b/doc/install/installation.md
index 32297c9c8f0..e79b8d6ce14 100644
--- a/doc/install/installation.md
+++ b/doc/install/installation.md
@@ -483,6 +483,9 @@ the `gitaly:` section is uncommented.
       gitaly:
         socket_path: tmp/sockets/private/gitaly.socket
 
+For more information about configuring Gitaly see
+[doc/administration/gitaly](../administration/gitaly).
+
 ### Setup Logrotate
 
     sudo cp lib/support/logrotate/gitlab /etc/logrotate.d/gitlab