Docs: add secondary geo node before db replication

As soon as the database is replicated the secondary will start behaving
as primary including attempting to write to the database which will fail
and cause errors. Moving this step prior avoids this.

doc/gitlab-geo/configuration.md

@@ -113,6 +113,12 @@ sensitive data in the database. Any secondary node must have the
     gitlab-ctl reconfigure
     ```
 
+Once reconfigured, the secondary will start automatically
+replicating missing data from the primary in a process known as backfill.
+Meanwhile, the primary node will start to notify changes to the secondary, which
+will act on those notifications immediately. Make sure the secondary instance is
+running and accessible.
+
 ### Step 3. Enabling hashed storage (from GitLab 10.0)
 
 1. Visit the **primary** node's **Admin Area ➔ Settings**
@@ -125,27 +131,18 @@ Using hashed storage significantly improves Geo replication - project and group
 renames no longer require synchronization between nodes - so we recommend it is
 used for all GitLab Geo installations.
 
-### Step 4. Enabling the secondary GitLab node
+### Step 4. Managing the secondary GitLab node
 
-1. Visit the **primary** node's **Admin Area ➔ Geo Nodes** (`/admin/geo_nodes`)
-   in your browser.
-1. Add the secondary node by providing its full URL. **Do NOT** check the box
-   'This is a primary node'.
-1. Added in GitLab 9.5: Choose which namespaces should be replicated by the secondary node. Leave blank to replicate all. Read more in [selective replication](#selective-replication).
-1. Click the **Add node** button.
-1. Restart GitLab on the secondary:
+You can monitor the status of the syncing process on a secondary node
+by visiting the primary node's **Admin Area ➔ Geo Nodes** (`/admin/geo_nodes`)
+in your browser.
 
-    ```
-    gitlab-ctl restart
-    ```
+Please note that if `git_data_dirs` is customized on the primary for multiple
+repository shards you must duplicate the same configuration on the secondary.
 
----
+![GitLab Geo dashboard](img/geo-node-dashboard.png)
 
-After the **Add Node** button is pressed, the secondary will start automatically
-replicating missing data from the primary in a process known as backfill.
-Meanwhile, the primary node will start to notify changes to the secondary, which
-will act on those notifications immediately. Make sure the secondary instance is
-running and accessible.
+Disabling a secondary node stops the syncing process.
 
 The two most obvious issues that replication can have here are:
 
@@ -164,17 +161,6 @@ Currently, this is what is synced:
 * Issue, merge request, snippet and comment attachments
 * User, group, and project avatars
 
-You can monitor the status of the syncing process on a secondary node
-by visiting the primary node's **Admin Area ➔ Geo Nodes** (`/admin/geo_nodes`)
-in your browser.
-
-Please note that if `git_data_dirs` is customized on the primary for multiple
-repository shards you must duplicate the same configuration on the secondary.
-
-![GitLab Geo dashboard](img/geo-node-dashboard.png)
-
-Disabling a secondary node stops the syncing process.
-
 ## Next steps
 
 Your nodes should now be ready to use. You can login to the secondary node

doc/gitlab-geo/configuration_source.md

@@ -106,6 +106,11 @@ sensitive data in the database. Any secondary node must have the
 
 1. Save and close the file.
 
+The secondary will start automatically replicating missing data from the
+primary in a process known as backfill. Meanwhile, the primary node will start
+to notify changes to the secondary, which will act on those notifications
+immediately. Make sure the secondary instance is running and accessible.
+
 ### Step 3. Enabling hashed storage (from GitLab 10.0)
 
 1. Visit the **primary** node's **Admin Area ➔ Settings**
@@ -119,27 +124,18 @@ renames no longer require synchronization between nodes - so we recommend it is
 used for all GitLab Geo installations.
 
 
-### Step 4. Enabling the secondary GitLab node
+### Step 4. Managing the secondary GitLab node
 
-1. Visit the **primary** node's **Admin Area ➔ Geo Nodes** (`/admin/geo_nodes`)
-   in your browser.
-1. Add the secondary node by providing its full URL. **Do NOT** check the box
-   'This is a primary node'.
-1. Added in GitLab 9.5: Choose which namespaces should be replicated by the secondary node. Leave blank to replicate all. Read more in [selective replication](#selective-replication).
-1. Click the **Add node** button.
-1. Restart GitLab on the secondary:
+You can monitor the status of the syncing process on a secondary node
+by visiting the primary node's **Admin Area ➔ Geo Nodes** (`/admin/geo_nodes`)
+in your browser.
 
-    ```
-    gitlab-ctl restart
-    ```
+Please note that if `git_data_dirs` is customized on the primary for multiple
+repository shards you must duplicate the same configuration on the secondary.
 
----
+![GitLab Geo dashboard](img/geo-node-dashboard.png)
 
-After the **Add Node** button is pressed, the secondary will start automatically
-replicating missing data from the primary in a process known as backfill.
-Meanwhile, the primary node will start to notify changes to the secondary, which
-will act on those notifications immediately. Make sure the secondary instance is
-running and accessible.
+Disabling a secondary node stops the syncing process.
 
 The two most obvious issues that replication can have here are:
 
@@ -162,13 +158,6 @@ You can monitor the status of the syncing process on a secondary node
 by visiting the primary node's **Admin Area ➔ Geo Nodes** (`/admin/geo_nodes`)
 in your browser.
 
-Please note that if `git_data_dirs` is customized on the primary for multiple
-repository shards you must duplicate the same configuration on the secondary.
-
-![GitLab Geo dashboard](img/geo-node-dashboard.png)
-
-Disabling a secondary node stops the syncing process.
-
 ## Next steps
 
 Your nodes should now be ready to use. You can login to the secondary node

doc/gitlab-geo/database.md

@@ -154,9 +154,23 @@ The following guide assumes that:
 1. Now that the PostgreSQL server is set up to accept remote connections, run
    `netstat -plnt` to make sure that PostgreSQL is listening to the server's
    public IP.
-1. Continue to [set up the secondary server](#step-2-configure-the-secondary-server).
 
-### Step 2. Configure the secondary server
+### Step 2. Add the secondary GitLab node
+
+To prevent the secondary geo node trying to act as the primary once the
+database is replicated, the secondary geo node must be configured on the
+primary before the database is replicated.
+
+1. Visit the **primary** node's **Admin Area ➔ Geo Nodes**
+   (`/admin/geo_nodes`) in your browser.
+1. Add the secondary node by providing its full URL. **Do NOT** check the box
+   'This is a primary node'.
+1. Added in GitLab 9.5: Choose which namespaces should be replicated by the
+   secondary node. Leave blank to replicate all. Read more in
+   [selective replication](#selective-replication).
+1. Click the **Add node** button.
+
+### Step 3. Configure the secondary server
 
 1. SSH into your GitLab **secondary** server and login as root:
 
@@ -197,7 +211,7 @@ The following guide assumes that:
     same time zone, but when the respective times are converted to UTC time,
     the clocks must be synchronized to within 60 seconds of each other.
 
-### Step 3. Initiate the replication process
+### Step 4. Initiate the replication process
 
 Below we provide a script that connects to the primary server, replicates the
 database and creates the needed files for replication.

doc/gitlab-geo/database_source.md

@@ -132,9 +132,23 @@ The following guide assumes that:
 1. Now that the PostgreSQL server is set up to accept remote connections, run
    `netstat -plnt` to make sure that PostgreSQL is listening to the server's
    public IP.
-1. Continue to [set up the secondary server](#step-2-configure-the-secondary-server).
 
-### Step 2. Configure the secondary server
+### Step 2. Add the secondary GitLab node
+
+To prevent the secondary geo node trying to act as the primary once the
+database is replicated, the secondary geo node must be configured on the
+primary before the database is replicated.
+
+1. Visit the **primary** node's **Admin Area ➔ Geo Nodes**
+   (`/admin/geo_nodes`) in your browser.
+1. Add the secondary node by providing its full URL. **Do NOT** check the box
+   'This is a primary node'.
+1. Added in GitLab 9.5: Choose which namespaces should be replicated by the
+   secondary node. Leave blank to replicate all. Read more in
+   [selective replication](#selective-replication).
+1. Click the **Add node** button.
+
+### Step 3. Configure the secondary server
 
 1. SSH into your GitLab **secondary** server and login as root:
 
@@ -226,7 +240,7 @@ the clocks must be synchronized to within 60 seconds of each other.
     bundle exec rake geo:db:migrate
     ```
 
-### Step 3. Initiate the replication process
+### Step 4. Initiate the replication process
 
 Below we provide a script that connects to the primary server, replicates the
 database and creates the needed files for replication.