Adding TOC

source/install/troubleshooting.rst

@@ -3,6 +3,11 @@
 Troubleshooting
 ===============
 
+This document summarizes common troubleshooting issues and techinques.
+
+.. contents::
+    :backlinks: top
+
 Important notes
 ---------------
 
@@ -132,51 +137,3 @@ Click the link at the bottom of the sign-in page that says “Don't have an acco
          1. Turning the sign-in option back on.
          2. Asking the user to switch sign-in methods before turning the
             sign-in option back off.
-
-GitLab Mattermost Error Messages
---------------------------------
-
-``We received an unexpected status code from the server (200)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you have upgraded from a pre-released version of GitLab Mattermost or if an unforseen issue has arrisen during the `upgrade procedure <http://docs.mattermost.com/administration/upgrade.html>`__, you may be able to restore Mattermost using the following procedure:
-
-   1. ``sudo stop mattermost``, so DB can be dropped
-   2. ``sudo gitlab-ctl reconfigure``
-   3. ``sudo -u gitlab-psql /opt/gitlab/embedded/bin/dropdb -h /var/opt/gitlab/postgresql mattermost_production``
-   4. ``sudo start mattermost``
-   5. ``sudo gitlab-ctl reconfigure``
-   6. `Manually set up GitLab SSO <http://docs.mattermost.com/deployment/sso-gitlab.html>`__ by copying Secret and ID into ``/var/opt/gitlab/mattermost/config.json``
-   7. ``sudo gitlab-ctl restart``
-
-``Token request failed``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This error can appear in the web browser after attempting to create a new team with GitLab SSO enabled
-
-Solutions:
-
-   1. Check that your SSL settings for the SSO provider match the ``http://`` or ``https://`` choice selected in ``config.json`` under ``GitLabSettings``
-   2. Follow steps 1 to 3 of the manual `GitLab SSO configuration procedure <http://docs.mattermost.com/deployment/sso-gitlab.html>`__ to confirm your ``Secret`` and ``Id`` settings in ``config.json`` match your GitLab settings, and if they don't, manually update ``config.json`` to the correct settings and see if this clears the issue.
-
-``The redirect URI included is not valid.``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This error may be related to SSL configurations in your proxy after a GitLab omnibus upgrade from 8.0, which contained the Mattermost beta version.
-
-Please check that each step of `the procedure for upgrading Mattermost in GitLab 8.0 to GitLab 8.1 was completed <http://docs.mattermost.com/integrations/gitlab.html#upgrading-from-gitlab-mattermost-beta>`__. Then check upgrades to successive major versions were completed using the procedure in the `Upgrade Guide <http://docs.mattermost.com/administration/upgrade.html>`__.
-
-``panic: The database schema version of 1.1.0 cannot be upgraded. You must not skip a version``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This error may appear in your ``/var/log/gitlab/mattermost/current`` if you're attempting to skip major versions when upgrading GitLab Mattermost (e.g. running an upgrade from GitLab 8.2.x to 8.4.x, instead of running from 8.2.x to 8.3.x to 8.4.x which is required for GitLab Mattermost). 
-
-To address this:
-   1. Run ``platform -version`` to check your version of Mattermost
-   2. If your version of the Mattermost binary doesn't match the version listed in the database error message, downgrade the version of the Mattermost binary you are using by `following the manual upgrade steps for Mattermost <http://docs.mattermost.com/administration/upgrade.html>`__ and using the database schema version listed in the error messages for the version you select in Step 1) iv).
-   3. Once Mattermost is working again, you can use the same upgrade procedure to upgrade Mattermost version by version to your current GitLab version. After this is done, GitLab automation should continue to work for future upgrades, so long as you don't skip versions.
-
-``panic: Error decoding config file=/opt/mattermost/config/config.json, err=invalid character '"' after object key:value pair``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Your ``config.json`` is not a well-formed ``.json`` file. Try using a `json validator <https://jsonformatter.curiousconcept.com/>`__ to find the error.