Put config.toml first in the documentation

1 files changed, 58 insertions, 50 deletions

diff --git a/doc/configuration/README.md b/doc/configuration/README.md
index a4431b53d..2b89f3c03 100644
--- a/doc/configuration/README.md
+++ b/doc/configuration/README.md
@@ -3,59 +3,20 @@
 This document describes how to configure the Gitaly server
 application.
 
-Gitaly is configured via environment variables that start with
-`GITALY_`. It depends on how you installed GitLab how you should go
-about setting these variables. See:
+Gitaly is configured via a [TOML](https://github.com/toml-lang/toml)
+configuration file. Where this TOML file is located and how you should
+edit it depend on how you installed GitLab. See:
 https://docs.gitlab.com/ce/administration/gitaly/
 
-## GITALY_SOCKET_PATH
+The configuration file is passed as an argument to the `gitaly`
+executable. This is usually done by either omnibus-gitlab or your init
+script.
 
-Required unless GITALY_LISTEN_ADDR is set.
-
-A path at which Gitaly should open a Unix socket. Example value:
-
-```
-GITALY_SOCKET_PATH=/home/git/gitlab/tmp/sockets/private/gitaly.socket
 ```
-
-## GITALY_LISTEN_ADDR
-
-Required unless GITALY_SOCKET_PATH is set.
-
-TCP address for Gitaly to listen on. Note: at the moment Gitaly does
-not offer any form of authentication. When you use a TCP listener you
-must use firewalls or other network-based security to restrict access
-to Gitaly.
-
-Example value:
-
-```
-GITALY_LISTEN_ADDR=localhost:1234
+gitaly /path/to/config.toml
 ```
 
-## GITALY_PROMETHEUS_LISTEN_ADDR
-
-Optional.
-
-TCP listen address for Prometheus metrics. When missing or empty, no
-Prometheus listener is started.
-
-```
-GITALY_PROMETHEUS_LISTEN_ADDR=localhost:9236
-```
-
-## Configuration file
-
-Gitaly also takes a path to a config-file as a command-line argument.
-
-```
-./gitaly /path/to/config.toml
-```
-
-*NOTE*: Environment variables currently takes percedence over the configuration
-file. But environment variables will be depricated at some point.
-
-### Format
+## Format
 
 ```toml
 socket_path = "/path/to/gitaly.sock"
@@ -72,8 +33,6 @@ name = "my_shard"
 #path = "/path/to/other/repositories"
 ```
 
-#### Explanation
-
 |name|type|required|notes|
 |----|----|--------|-----|
 |socket_path|string|see notes|A path which gitaly should open a Unix socket. Required unless listen_addr is set|
@@ -81,9 +40,58 @@ name = "my_shard"
 |prometheus_listen_addr|string|no|TCP listen address for Prometheus metrics. If not set, no Prometheus listener is started|
 |storage|array|yes|An array of storage shards|
 
-##### Storage
+### Storage
+
+GitLab repositories are grouped into 'storages'. These are directories containing bare repositories managed by GitLab, with logical names.
+
+These names and paths are also defined in the `gitlab.yml`
+configuration file of gitlab-ce (or gitlab-ee). When you run Gitaly on
+the same machine as gitlab-ce, which is the default and recommended
+configuration, storage paths defined in Gitaly's config.toml must
+match those in gitlab.yml.
 
 |name|type|required|notes|
 |----|----|--------|-----|
 |path|string|yes|Path to storage shard|
 |name|string|yes|Name of storage shard|
+
+## Legacy environment variables
+
+These were used to configure earlier version of Gitaly. When present,
+they take precendence over the configuration file.
+
+### GITALY_SOCKET_PATH
+
+Required unless GITALY_LISTEN_ADDR is set.
+
+A path at which Gitaly should open a Unix socket. Example value:
+
+```
+GITALY_SOCKET_PATH=/home/git/gitlab/tmp/sockets/private/gitaly.socket
+```
+
+### GITALY_LISTEN_ADDR
+
+Required unless GITALY_SOCKET_PATH is set.
+
+TCP address for Gitaly to listen on. Note: at the moment Gitaly does
+not offer any form of authentication. When you use a TCP listener you
+must use firewalls or other network-based security to restrict access
+to Gitaly.
+
+Example value:
+
+```
+GITALY_LISTEN_ADDR=localhost:1234
+```
+
+### GITALY_PROMETHEUS_LISTEN_ADDR
+
+Optional.
+
+TCP listen address for Prometheus metrics. When missing or empty, no
+Prometheus listener is started.
+
+```
+GITALY_PROMETHEUS_LISTEN_ADDR=localhost:9236
+```