Merge branch 'docs/praefect-doc-improvements' into 'master'

Add more details to the Praefect setup docs

Closes gitaly#2073

See merge request gitlab-org/gitlab!18447

doc/administration/gitaly/praefect.md

@@ -25,40 +25,43 @@ three Gitaly nodes, `Praefect-Git-1`,  `Praefect-Git-2`, and `Praefect-Git-3`.
 There should be no knowledge other than with Praefect about the existence of
 the `Praefect-Git-X` nodes.
 
-### Enable the daemon
+### Setup
 
-Praefect is expected to run on their own host, this means that no other service
-other than the support services run on this machine.
+In this setup guide, the Gitaly node will be added first, then Praefect, and
+lastly we update the GitLab configuration.
 
-Praefect is disabled by default, to enable praefect uncomment the following line
-and set it to `true`: `# praefect['enable'] = false'`
+#### Gitaly
 
-```ruby
-praefect['enable'] = true
-```
-
-By default praefect will listen on port `:2305`. It's recommended to enable
-prometheus to expose metrics. Uncomment the line so it looks like:
-
-```ruby
-praefect['prometheus_listen_addr'] = "localhost:9652"
-```
+In their own machine, configure the Gitaly server as described in the
+[gitaly documentation](index.md#3-gitaly-server-configuration).
 
-Preafect needs at least one storage to store the Git data on. This node should
-run Gitaly and should not be listed as storage for GitLab itself, that is, the
-only way it receives traffic is through Praefect and it's not listed in the
-`git_data_dirs` on any `gitlab.rb` in your GitLab cluster.
+#### Praefect
 
-To set the nodes as depicted in the diagram above, the configuration should look
-like:
+Next, Praefect has to be enabled on its own node. Disable all other services,
+and add each Gitaly node that will be connected to Praefect. In the example below,
+the Gitaly nodes are named `praefect-git-X`. Note that one node is designated as
+primary, by setting the primary to `true`:
 
 ```ruby
+# /etc/gitlab/gitlab.rb
+
+# Avoid running unnecessary services on the Gitaly server
+postgresql['enable'] = false
+redis['enable'] = false
+nginx['enable'] = false
+prometheus['enable'] = false
+unicorn['enable'] = false
+sidekiq['enable'] = false
+gitlab_workhorse['enable'] = false
+gitaly['enable'] = false
+
+praefect['enable'] = true
 praefect['storage_nodes'] = [
   {
     'storage' => 'praefect-git-1',
     'address' => 'tcp://praefect-git-1.internal',
     'primary' => true
-}
+  },
   {
     'storage' => 'praefect-git-2',
     'address' => 'tcp://praefect-git-2.internal'
@@ -70,10 +73,9 @@ praefect['storage_nodes'] = [
 ]
 ```
 
-Save the file, and run `gitlab-ctl reconfigure`. To test if Praefect is running,
-you could run `gitlab-ctl status` which should list praefect as being up.
+Save the file and [reconfigure Praefect](../restart_gitlab.md#omnibus-gitlab-reconfigure).
 
-### Enable Preafect as storage backend in GitLab
+#### GitLab
 
 When Praefect is running, it should be exposed as a storage to GitLab. This
 is done through setting the `git_data_dirs`. Assuming the default storage