Add more information

- Add FAQ about different SSH port
- Add section on using a custom name for the SSH key pair
- Change image for Geo nodes admin area
- Reorganize some sections

[ci skip]

doc/administration/gitlab-geo/README.md

@@ -18,6 +18,7 @@ locations as a read-only fully operational version.
     - [What data is replicated to a secondary node?](#what-data-is-replicated-to-a-secondary-node)
     - [Can I git push to a secondary node?](#can-i-git-push-to-a-secondary-node)
     - [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 -->
 
@@ -36,6 +37,12 @@ distances much faster.
 When Geo is enabled, we refer to your original instance as a **primary** node
 and the replicated read-only ones as **secondaries**.
 
+Keep in mind that:
+
+- Secondaries talk to primary to get user data for logins (API), and to
+  clone/pull from repositories (HTTP(S)/SSH).
+- Primary talks to secondaries to notify for changes (API).
+
 ## Setup instructions
 
 GitLab Geo requires some additional work installing and configuring your
@@ -48,7 +55,6 @@ Geo instances. Follow the steps below in the order that they appear:
    secondary Geo node
 1. [Setup a database replication](./database.md) in `master <-> slave` 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:
 
@@ -95,3 +101,9 @@ All replication operations are asynchronous and are queued to be dispatched in
 a batched request every 10 seconds. Besides that, it depends on a lot of other
 factors including the amount of traffic, how big your commit is, the
 connectivity between your nodes, your hardware, etc.
+
+### What happens if the SSH server runs at a different port?
+
+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.

doc/administration/gitlab-geo/configuration.md

@@ -48,8 +48,8 @@ GitLab instance runs on (unless changed, should be the user `git`). This user
 will act as a "normal user" who fetches from the primary Geo node.
 
 Run the command below on each server that will be a Geo node (primary or
-secondary), and paste the contents of `id_rsa.pub` to the admin area
-(**Admin Area > Geo Nodes**) when adding a new node:
+secondary), and paste the contents of `id_rsa.pub` to the admin area of the
+primary node (**Admin Area > Geo Nodes**) when adding a new one:
 
 ```bash
 sudo -u git -H ssh-keygen
@@ -58,6 +58,26 @@ sudo -u git -H ssh-keygen
 The public key for Omnibus installations will be at `/var/opt/gitlab/.ssh/id_rsa.pub`,
 whereas for installation from source it will be at `/home/git/.ssh/id_rsa.pub`.
 
+If for any reason you generate the key using a different name from the default
+`id_rsa`, or you want to generate an extra key only for the repository
+synchronization feature, you can do so, but you have to create/modify your
+`~/.ssh/config` (for the `git` user).
+
+This is an example on how to change the default key for all remote hosts:
+
+```bash
+Host *                              # Match all remote hosts
+  IdentityFile ~/.ssh/mycustom.key  # The location of your private key
+```
+
+This is how to change it for an specific host:
+
+```bash
+Host example.com                    # The FQDN of the primary Geo node
+  HostName example.com              # The FQDN of the primary Geo node
+  IdentityFile ~/.ssh/mycustom.key  # The location of your private key
+```
+
 ## Primary Node GitLab setup
 
 >**Note:**
@@ -67,17 +87,10 @@ instance. If you haven't done that already, read [database replication](./databa
 
 Go to the server that you chose to be your primary, and visit
 **Admin Area > Geo Nodes** (`/admin/geo_nodes`) in order to add the Geo nodes.
-Although we are looking at the primary Geo node setup, this is where you also
-add any secondary servers as well.
+Although we are looking at the primary Geo node setup, **this is where you also
+add any secondary servers as well**.
 
-The very first node you add must be your primary, and the rest are the secondary
-ones. Make sure to check the box 'This is a primary node' when adding it.
-
-![Geo Nodes Screen](img/geo-nodes-screen.png)
-
----
-
-In the following table you can see what all these settings mean.
+In the following table you can see what all these settings mean:
 
 | Setting | Description |
 | ------- | ----------- |
@@ -85,8 +98,20 @@ In the following table you can see what all these settings mean.
 | URL | Your instance's full URL, in the same way it is configured in `gitlab.yml` (source based installations) or `/etc/gitlab/gitlab.rb` (omnibus installations). |
 |Public Key | The SSH public key of the user that your GitLab instance runs on (unless changed, should be the user `git`). That means that you have to go in each Geo Node separately and create an SSH key pair. See the [SSH key creation](#create-ssh-key-pairs-for-geo-nodes) section.
 
+First, add your primary node by providing its full URL and the public SSH key
+you created previously. Make sure to check the box 'This is a primary node'
+when adding it. Continue with all secondaries.
+
+![Geo Nodes Screen](img/geo-nodes-screen.png)
+
+---
+
 ## Secondary Node GitLab setup
 
+>**Note:**
+The Geo nodes admin area (**Admin Area > Geo Nodes**) is not used when setting
+up the secondary servers. This is handled by the primary server setup.
+
 To install a secondary node, you must follow the normal GitLab Enterprise
 Edition installation, with some extra requirements: