Move troubleshooting section in its own document

[ci skip]

doc/gitlab-geo/README.md

@@ -71,6 +71,10 @@ If you installed GitLab from source:
 
 Read more in the [Geo FAQ](faq.md).
 
+## Troubleshooting
+
+Read the [troubleshooting document](troubleshooting.md).
+
 [ee]: https://about.gitlab.com/gitlab-ee/ "GitLab Enterprise Edition landing page"
 [install-ee]: https://about.gitlab.com/downloads-ee/ "GitLab Enterprise Edition Omnibus packages downloads page"
 [install-ee-source]: https://docs.gitlab.com/ee/install/installation.html "GitLab Enterprise Edition installation from source"

doc/gitlab-geo/configuration.md

@@ -290,60 +290,4 @@ Host example.com                    # The FQDN of the primary Geo node
 
 ## Troubleshooting
 
->**Note:**
-This list is an attempt to document all the moving parts that can go wrong.
-We are working into getting all this steps verified automatically in a
-rake task in the future.
-
-Setting up Geo requires careful attention to details and sometimes it's easy to
-miss a step. Here is a checklist of questions you should ask to try to detect
-where you have to fix (all commands and path locations are for Omnibus installs):
-
-- Is Postgres replication working?
-- Are my nodes pointing to the correct database instance?
-    - You should make sure your primary Geo node points to the instance with
-      writing permissions.
-    - Any secondary nodes should point only to read-only instances.
-- Can Geo detect my current node correctly?
-    - Geo uses your defined node from `Admin ➔ Geo` screen, and tries to match
-      with the value defined in `/etc/gitlab/gitlab.rb` configuration file.
-      The relevant line looks like: `external_url "http://gitlab.example.com"`.
-    - To check if node on current machine is correctly detected type:
-
-        ```
-        sudo gitlab-rails runner "puts Gitlab::Geo.current_node.inspect"
-        ```
-
-        and expect something like:
-
-        ```
-        #<GeoNode id: 2, schema: "https", host: "gitlab.example.com", port: 443, relative_url_root: "", primary: false, ...>
-        ```
-
-    - By running the command above, `primary` should be `true` when executed in
-      the primary node, and `false` on any secondary
-- Did I define the correct SSH Key for the node?
-    - You must create an SSH Key for `git` user
-    - This key is the one you have to inform at `Admin > Geo`
-- Can I SSH from secondary to primary node using `git` user account?
-    - This is the most obvious cause of problems with repository replication issues.
-      If you haven't added the primary node's key to `known_hosts`, you will end up with
-      a lot of failed sidekiq jobs with an error similar to:
-
-        ```
-        Gitlab::Shell::Error: Host key verification failed. fatal: Could not read from remote repository. Please make sure you have the correct access rights and the repository exists.
-        ```
-
-        An easy way to fix is by logging in as the `git` user in the secondary node and run:
-
-        ```
-        # remove old entries to your primary gitlab in known_hosts
-        ssh-keyscan -R your-primary-gitlab.example.com
-
-        # add a new entry in known_hosts
-        ssh-keyscan -t rsa your-primary-gitlab.example.com >> ~/.ssh/known_hosts
-        ```
-- Can primary node communicate with secondary node by HTTP/HTTPS ports?
-- Can secondary nodes communicate with primary node by HTTP/HTTPS/SSH ports?
-- Can secondary nodes execute a successful git clone using git user's own
-  SSH Key to primary node repository?
+See the [troubleshooting document](troubleshooting.md).

doc/gitlab-geo/configuration_source.md

@@ -268,4 +268,4 @@ Read [Additional information for the SSH key pairs](configuration.md#additional-
 
 ## Troubleshooting
 
-Read the [Omnibus troubleshooting section](configuration.md#troubleshooting).
+Read the [troubleshooting document](troubleshooting.md).

doc/gitlab-geo/database.md

@@ -241,5 +241,9 @@ Now that the database replication is done, the next step is to configure GitLab.
 
 We don't support MySQL replication for GitLab Geo.
 
+## Troubleshooting
+
+Read the [troubleshooting document](troubleshooting.md).
+
 [pgback]: http://www.postgresql.org/docs/9.2/static/app-pgbasebackup.html
 [reconfigure GitLab]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure

doc/gitlab-geo/database_source.md

@@ -226,5 +226,9 @@ Now that the database replication is done, the next step is to configure GitLab.
 
 We don't support MySQL replication for GitLab Geo.
 
+## Troubleshooting
+
+Read the [troubleshooting document](troubleshooting.md).
+
 [pgback]: http://www.postgresql.org/docs/9.2/static/app-pgbasebackup.html
 [reconfigure GitLab]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure

doc/gitlab-geo/troubleshooting.md

+# GitLab Geo troubleshooting
+
+>**Note:**
+This list is an attempt to document all the moving parts that can go wrong.
+We are working into getting all this steps verified automatically in a
+rake task in the future.
+
+Setting up Geo requires careful attention to details and sometimes it's easy to
+miss a step. Here is a checklist of questions you should ask to try to detect
+where you have to fix (all commands and path locations are for Omnibus installs):
+
+- Is Postgres replication working?
+- Are my nodes pointing to the correct database instance?
+    - You should make sure your primary Geo node points to the instance with
+      writing permissions.
+    - Any secondary nodes should point only to read-only instances.
+- Can Geo detect my current node correctly?
+    - Geo uses your defined node from `Admin ➔ Geo` screen, and tries to match
+      with the value defined in `/etc/gitlab/gitlab.rb` configuration file.
+      The relevant line looks like: `external_url "http://gitlab.example.com"`.
+    - To check if node on current machine is correctly detected type:
+
+        ```
+        sudo gitlab-rails runner "puts Gitlab::Geo.current_node.inspect"
+        ```
+
+        and expect something like:
+
+        ```
+        #<GeoNode id: 2, schema: "https", host: "gitlab.example.com", port: 443, relative_url_root: "", primary: false, ...>
+        ```
+
+    - By running the command above, `primary` should be `true` when executed in
+      the primary node, and `false` on any secondary
+- Did I define the correct SSH Key for the node?
+    - You must create an SSH Key for `git` user
+    - This key is the one you have to inform at `Admin > Geo`
+- Can I SSH from secondary to primary node using `git` user account?
+    - This is the most obvious cause of problems with repository replication issues.
+      If you haven't added the primary node's key to `known_hosts`, you will end up with
+      a lot of failed sidekiq jobs with an error similar to:
+
+        ```
+        Gitlab::Shell::Error: Host key verification failed. fatal: Could not read from remote repository. Please make sure you have the correct access rights and the repository exists.
+        ```
+
+        An easy way to fix is by logging in as the `git` user in the secondary node and run:
+
+        ```
+        # remove old entries to your primary gitlab in known_hosts
+        ssh-keyscan -R your-primary-gitlab.example.com