Merge branch 'sh-improve-geo-docs' into 'master'

Add more details to clarify GitLab Geo installation

See merge request !1175

doc/gitlab-geo/configuration.md

@@ -139,10 +139,10 @@ sensitive data in the database. Any secondary node must have the
 
      ```
      # Omnibus GitLab installations
-     cat /etc/gitlab/gitlab-secrets.json
+     cat /etc/gitlab/gitlab-secrets.json | grep db_key_base
 
      # Installations from source
-     cat /home/git/gitlab/config/secrets.yml
+     cat /home/git/gitlab/config/secrets.yml | grep db_key_base
      ```
 
 1. SSH into the **secondary** node and login as root:

doc/gitlab-geo/database.md

@@ -76,8 +76,33 @@ The following guide assumes that:
     ```
 
     Where `1.2.3.4` is the public IP address of the primary server, and `5.6.7.8`
-    the public IP address of the secondary one. If you want to add another
-    secondary, the relevant setting would look like:
+    the public IP address of the secondary one.
+
+    For security reasons, PostgreSQL by default only listens on the local
+    interface (e.g. 127.0.0.1). However, GitLab Geo needs to communicate
+    between the primary and secondary nodes over a common network, such as a
+    corporate LAN or the public Internet. For this reason, we need to
+    configure PostgreSQL to listen on more interfaces.
+
+    The `listen_address` option opens PostgreSQL up to external connections
+    with the interface corresponding to the given IP. See [the PostgreSQL
+    documentation](https://www.postgresql.org/docs/9.6/static/runtime-config-connection.html)
+    for more details.
+
+    Note that if you are running GitLab Geo with a cloud provider (e.g. Amazon
+    Web Services), the internal interface IP (as provided by `ifconfig`) may
+    be different from the public IP address. For example, suppose you have a
+    nodes with the following configuration:
+
+    |Node Type|Internal IP|External IP|
+    |---------|-----------|-----------|
+    |Primary|10.1.5.3|54.193.124.100|
+    |Secondary|10.1.10.5|54.193.100.155|
+
+    In this case, for `1.2.3.4` use the internal IP of the primary node: 10.1.5.3.
+    For `5.6.7.8`, use the external of the secondary node: 54.193.100.155.
+
+    If you want to add another secondary, the relevant setting would look like:
 
     ```ruby
     postgresql['md5_auth_cidr_addresses'] = ['5.6.7.8/32','11.22.33.44/32']
@@ -85,6 +110,8 @@ The following guide assumes that:
 
     Edit the `wal` values as you see fit.
 
+1. Check to make sure your firewall rules are set so that the secondary nodes
+   can access port 5432 on the primary node.
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 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
@@ -119,6 +146,8 @@ The following guide assumes that:
     hot_standby = on
     ```
 
+    See the Omnibus notes above for more details of `listen_address`.
+
     Edit the `wal` values as you see fit.
 
 1. Set the access control on the primary to allow TCP connections using the