Merge branch 'geo-docs-8-13x' into 'master'

Improve Geo documentation for 8.13

This merge-request was initiated after feedback from costumers about our documentation.

It's a bunch of small fixes to add extra troubleshooting and improve the understanding of the required steps.

# Documentation changes/added:

- [x] Add "Host key verification" troubleshooting doc for Geo
- [x] Update rsync instructions to preserve repository user/group ownership
- [x] Communicate better the setup steps and the correct order they must happen

cc @dewetblomerus @marin

See merge request !766

doc/gitlab-geo/README.md

@@ -20,8 +20,6 @@ locations as a read-only fully operational version.
     - [How long does it take to have a commit replicated to a secondary node?](#how-long-does-it-take-to-have-a-commit-replicated-to-a-secondary-node)
     - [What happens if the SSH server runs at a different port?](#what-happens-if-the-ssh-server-runs-at-a-different-port)
 
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## Overview
 
 If you have two or more teams geographically spread out, but your GitLab
@@ -49,19 +47,35 @@ GitLab Geo requires some additional work installing and configuring your
 instance, than a normal setup.
 
 There are a couple of things you need to do in order to have one or more GitLab
-Geo instances. Follow the steps below in the order that they appear:
+Geo instances. Follow the steps below in the **exact order** that they appear:
+
+1. Follow the instructions to [install GitLab Enterprise Edition][install-ee]
+   on the server that will serve as the secondary Geo node, but don't further
+   configure GitLab as authentication will be handled by the primary node (more
+   on this in the configuration step).
+1. [Setup a database replication](database.md) in `primary <-> secondary (read-only)` topology.
+1. [Configure GitLab](configuration.md) and set the primary and secondary nodes.
+
+## After setup
 
-1. Install GitLab Enterprise Edition on the server that will serve as the
-   secondary Geo node
-1. [Setup a database replication](database.md) in `primary <-> secondary (read-only)` topology
-1. [Configure GitLab](configuration.md) and set the primary and secondary nodes
 After you set up the database replication and configure the GitLab Geo nodes,
 there are a few things to consider:
 
 1. When you create a new project in the primary node, the Git repository will
-   appear in the secondary only _after_ the first `git push`
-1. To fetch from the secondary node, a separate remote URL must be set in your
-   Git repository locally
+   appear in the secondary only _after_ the first `git push`.
+1. You need an extra step to be able to fetch code from the `secondary` and push
+   to `primary`:
+
+     1. Clone your repository as you would normally do from the `secondary` node
+     1. Change the remote push URL following this example:
+
+         ```bash
+         git remote set-url --push origin git@primary.gitlab.example.com:user/repo.git
+         ```
+
+> **Important**: The initialization of a new Geo secondary node requires data
+to be copied from the primary, as there is no backfill feature bundled with it.
+See more details in the [Configure GitLab](configuration.md) step.
 
 ## Current limitations
 
@@ -78,8 +92,8 @@ There are limitations to what we replicate (see Current limitations).
 In an extreme data-loss situation you can make a secondary Geo into your
 primary, but this is not officially supported yet.
 
-If you still want to proceed, see our step-by-step instructions on how to 
-manually [promote a secondary node](disaster-recovery.md) into primary. 
+If you still want to proceed, see our step-by-step instructions on how to
+manually [promote a secondary node](disaster-recovery.md) into primary.
 
 ### What data is replicated to a secondary node?
 
@@ -107,3 +121,5 @@ connectivity between your nodes, your hardware, etc.
 We send the clone url from the primary server to any secondaries, so it
 doesn't matter. If primary is running on port `2200` clone url will reflect
 that.
+
+[install-ee]: https://about.gitlab.com/downloads-ee/

doc/gitlab-geo/database.md

@@ -14,7 +14,7 @@ and `secondary` as either `slave` or `standby` server (read-only).
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+**Table of Contents**
 
 - [PostgreSQL replication](#postgresql-replication)
     - [PostgreSQL - Configure the primary server](#postgresql-configure-the-primary-server)