summaryrefslogtreecommitdiffstats
path: root/doc/install
diff options
context:
space:
mode:
Diffstat (limited to 'doc/install')
-rw-r--r--doc/install/Administration.md95
-rw-r--r--doc/install/Command-Line-Tools.md81
-rw-r--r--doc/install/Configuration-Settings.md45
-rw-r--r--doc/install/Production-Ubuntu.md18
-rw-r--r--doc/install/Requirements.md6
-rw-r--r--doc/install/Troubleshooting.md34
-rw-r--r--doc/install/Upgrade-Guide.md12
7 files changed, 258 insertions, 33 deletions
diff --git a/doc/install/Administration.md b/doc/install/Administration.md
index ee996088c..c51022da1 100644
--- a/doc/install/Administration.md
+++ b/doc/install/Administration.md
@@ -17,3 +17,98 @@ This document provides instructions for common administrator tasks
- Team Admin or System Admin can go to **Main Menu** > **Manage Members** > **Make Inactive** to deactivate a user, which removes them from the team.
- To preserve audit history, users are never deleted from the system. It is highly recommended that System Administrators do not attempt to delete users manually from the database, as this may compromise system integrity and ability to upgrade in future.
+
+## GitLab Mattermost Administration
+
+GitLab Mattermost is a special version of Mattermost bundled with GitLab omnibus. Here we consolidate administrative instructions, guides and troubleshooting guidance.
+
+### Installing GitLab Mattermost
+
+Please follow the [GitLab Omnibus documentation for installing GitLab Mattermost](http://doc.gitlab.com/omnibus/gitlab-mattermost/).
+
+### Community Support Resources
+
+For help and support around your GitLab Mattermost deployment please see:
+
+- [Troubleshooting Forum](https://forum.mattermost.org/t/about-the-trouble-shooting-category/150/1)
+- [GitLab Mattermost issue tracker on GitLab.com](https://gitlab.com/gitlab-org/gitlab-mattermost/issues)
+
+### Connecting Mattermost to integrations with incoming webhooks
+
+#### Connecting Mattermost to GitLab for Slack-equivalent functionality.
+
+Mattermost is designed to be _Slack-compatible, not Slack-limited_ and supports integration via the Slack UI in GitLab, as well as fully customizable integrations.
+
+To enable this:
+
+1. In Mattermost, from a team site where you have System Administration privileges, from the main menu go to **System Console** > **Serice Settings** > **Enable Incoming Webhooks** and select **true** then click **Save**
+
+2. Follow the step-by-step example of [connecting Mattermost incoming webhooks to GitLab's Slack webhooks UI](https://github.com/mattermost/platform/blob/master/doc/integrations/webhooks/Incoming-Webhooks.md#connecting-mattermost-to-gitlab-using-slack-ui).
+
+#### Connecting Mattermost to GitLab for functionality exceeding Slack integration.
+
+To enable this:
+
+1. In Mattermost, from a team site where you have System Administration privileges, from the main menu go to **System Console** > **Serice Settings** > **Enable Incoming Webhooks** and select **true** then click **Save**
+
+2. Set up the [GitLab Integration Service for Mattermost](https://github.com/mattermost/mattermost-integration-gitlab).
+
+### Connecting Mattermost to integrations with outgoing webhooks
+
+Mattermost offers Slack-compatible outgoing webhooks, that can connect to applications created by the Mattermost community, such as [Hubot](https://www.npmjs.com/package/hubot-mattermost) and [IRC](https://github.com/42wim/matterbridge) support.
+
+To enable this:
+
+1. In Mattermost, from a team site where you have System Administration privileges, from the main menu go to **System Console** > **Serice Settings** > **Enable Outgoing Webhooks** and select **true** then click **Save**
+
+2. Select a [Mattermost community application](http://www.mattermost.org/community-applications/) using outgoing webhooks--or adapt a Slack application using the same outgoing webhook standard--and follow the setup instructions provided.
+
+### Upgrading GitLab Mattermost manually
+
+If you choose to upgrade Mattermost outside of GitLab's omnibus automation, please [follow this guide](https://github.com/mattermost/platform/blob/master/doc/install/Upgrade-Guide.md#upgrading-mattermost-to-next-major-release).
+
+### Upgrading GitLab Mattermost from GitLab 8.0 (containing Mattermost 0.7.1-beta)
+
+To upgrade GitLab Mattermost from the 0.7.1-beta release of Mattermost in GitLab 8.0, please [follow this guide](https://github.com/mattermost/platform/blob/master/doc/install/Upgrade-Guide.md#upgrading-mattermost-in-gitlab-80-to-gitlab-81-with-omnibus).
+
+### Troubleshooting GitLab Mattermost
+
+- If you're having issues installing GitLab Mattermost with GitLab Omnibus, as a first step please turn on logging by updating the [log settings](https://github.com/mattermost/platform/blob/master/doc/install/Configuration-Settings.md#log-file-settings) section in your `config.json` file installed by omnibus, and they try a general web search for the error message you receive.
+
+#### 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](https://github.com/mattermost/platform/blob/master/doc/install/Upgrade-Guide.md), you may be able to restore Mattermost using the following procedure:
+ - `sudo stop mattermost`, so DB can be dropped
+ - `sudo gitlab-ctl reconfigure`
+ - `sudo -u gitlab-psql /opt/gitlab/embedded/bin/dropdb -h /var/opt/gitlab/postgresql mattermost_production`
+ - `sudo start mattermost`
+ - `sudo gitlab-ctl reconfigure`
+ - [Manually set up GitLab SSO](https://github.com/mattermost/platform/blob/master/doc/integrations/Single-Sign-On/Gitlab.md) by copying Secret and ID into `/var/opt/gitlab/mattermost/config.json`
+ - `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](https://github.com/mattermost/platform/blob/master/doc/integrations/Single-Sign-On/Gitlab.md) 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.
+ - **Solution:**
+ - Please check that each step of [the procedure for upgrading Mattermost in GitLab 8.0 to GitLab 8.1 was completed](https://github.com/mattermost/platform/blob/master/doc/install/Upgrade-Guide.md#upgrading-mattermost-in-gitlab-80-to-gitlab-81-with-omnibus). Then check upgrades to successive major versions were completed using the procedure in the [Upgrade Guide](https://github.com/mattermost/platform/blob/master/doc/install/Upgrade-Guide.md#upgrading-mattermost-to-next-major-release).
+
+
+###### `We couldn't find the existing account`
+ - This error appears when a user attempts to sign in using a single-sign-on option with an account that was not created using that single-sign-on option. For example, if a user creates Account A using email sign-up, then attempts to sign-in using GitLab SSO, the error appears since Account A was not created using GitLab SSO.
+ - **Solution:**
+ - If you're switching from email auth to GitLab SSO, and you're getting this issue on an admin account, consider deactivating your email-based account, then creating a new account with System Admin privileges using GitLab SSO. Specifically:
+ 1. Deactivate your email-based System Admin account (note: this process is [scheduled to improve](https://mattermost.atlassian.net/browse/PLT-975))
+ 1. Temporarily turn off email verification (**System Console** > **Email Settings** > **Require Email Verification** > **false**, or set `"RequireEmailVerification": false` in `config.json`).
+ 2. Change email for account to random address so you can create a new GitLab SSO account using your regular address.
+ 2. Create a new Mattermost account using GitLab SSO
+ 1. With GitLab SSO enabled, go to `https://domain.com/teamname` and sign-up for a new Mattermost account using your GitLab SSO account with preferred email address.
+ 2. [Upgrade the new account to System Admin privileges](https://github.com/mattermost/platform/blob/master/doc/install/Troubleshooting.md#lost-system-administrator-account).
+ 3. Deactivate the previous System Admin account that used email authentication.
+ 1. Using the new GitLab SSO System Admin account go to **System Console** > **[TEAMNAME]** > **Users**, find the previous account and set it to "Inactive"
diff --git a/doc/install/Command-Line-Tools.md b/doc/install/Command-Line-Tools.md
new file mode 100644
index 000000000..ff6f110fd
--- /dev/null
+++ b/doc/install/Command-Line-Tools.md
@@ -0,0 +1,81 @@
+# Command Line Tools
+
+From the directory where the Mattermost platform is installed a `platform` command is available for configuring the system, including:
+
+- Creating teams
+- Creating users
+- Assigning roles to users
+- Reseting user passwords
+- Permanently deleting users (use cautiously - database backup recommended before use)
+- Permanently deleting teams (use cautiously - database backup recommended before use)
+
+Typing `platform -help` brings up the below documentation on usage.
+
+```
+Mattermost commands to help configure the system
+
+NAME:
+ platform -- platform configuation tool
+
+USAGE:
+ platform [options]
+
+FLAGS:
+ -config="config.json" Path to the config file
+
+ -email="user@example.com" Email address used in other commands
+
+ -password="mypassword" Password used in other commands
+
+ -team_name="name" The team name used in other commands
+
+ -role="admin" The role used in other commands
+ valid values are
+ "" - The empty role is basic user
+ permissions
+ "admin" - Represents a team admin and
+ is used to help administer one team.
+ "system_admin" - Represents a system
+ admin who has access to all teams
+ and configuration settings.
+COMMANDS:
+ -create_team Creates a team. It requires the -team_name
+ and -email flag to create a team.
+ Example:
+ platform -create_team -team_name="name" -email="user@example.com"
+
+ -create_user Creates a user. It requires the -team_name,
+ -email and -password flag to create a user.
+ Example:
+ platform -create_user -team_name="name" -email="user@example.com" -password="mypassword"
+
+ -assign_role Assigns role to a user. It requires the -role,
+ -email and -team_name flag. You may need to log out
+ of your current sessions for the new role to be
+ applied.
+ Example:
+ platform -assign_role -team_name="name" -email="user@example.com" -role="admin"
+
+ -reset_password Resets the password for a user. It requires the
+ -team_name, -email and -password flag.
+ Example:
+ platform -reset_password -team_name="name" -email="user@example.com" -password="newpassword"
+
+ -permanent_delete_user Permanently deletes a user and all related information
+ including posts from the database. It requires the
+ -team_name, and -email flag. You may need to restart the
+ server to invalidate the cache
+ Example:
+ platform -permanent_delete_user -team_name="name" -email="user@example.com"
+
+ -permanent_delete_team Permanently deletes a team and all users along with
+ all related information including posts from the database.
+ It requires the -team_name flag. You may need to restart
+ the server to invalidate the cache.
+ Example:
+ platform -permanent_delete_team -team_name="name"
+
+ -version Display the current of the Mattermost platform
+
+ -help Displays this help page`
+```
diff --git a/doc/install/Configuration-Settings.md b/doc/install/Configuration-Settings.md
index a92893753..5f9b3b62d 100644
--- a/doc/install/Configuration-Settings.md
+++ b/doc/install/Configuration-Settings.md
@@ -29,7 +29,12 @@ Set this key to enable embedding of YouTube video previews based on hyperlinks a
#### Webhooks
```"EnableIncomingWebhooks": true```
-Developers building integrations can create webhook URLs for channels and private groups. Please see http://mattermost.org/webhooks to learn about creating webhooks, view samples, and to let the community know about integrations you have built. "true": Incoming webhooks will be allowed. To manage incoming webhooks, go to Account Settings -> Integrations. The webhook URLs created in Account Settings can be used by external applications to create posts in any channels or private groups that you have access to; “false”: The Integrations tab of Account Settings is hidden and incoming webhooks are disabled.
+Developers building integrations can create webhook URLs for channels and private groups. Please see http://mattermost.org/webhooks to learn about creating webhooks, view samples, and to let the community know about integrations you have built. "true": Incoming webhooks will be allowed. To manage incoming webhooks, go to **Account Settings -> Integrations**. The webhook URLs created in Account Settings can be used by external applications to create posts in any channels or private groups that you have access to; “false”: The Integrations > Incoming Webhooks section of Account Settings is hidden and all incoming webhooks are disabled.
+
+Security note: By enabling this feature, users may be able to perform [phishing attacks](https://en.wikipedia.org/wiki/Phishing) by attempting to impersonate other users. To combat these attacks, a BOT tag appears next to all posts from a webhook. Enable at your own risk.
+
+```"EnableOutgoingWebhooks": true```
+Developers building integrations can create webhook tokens for public channels. Trigger words are used to fire new message events to external integrations. For security reasons, outgoing webhooks are only available in public channels. Please see our [documentation page](https://github.com/mattermost/platform/blob/master/doc/integrations/webhooks/Outgoing-Webhooks.md) to learn about creating webhooks and view samples. "true": Outgoing webhooks will be allowed. To manage outgoing webhooks, go to **Account Settings -> Integrations**; “false”: The Integrations > Outgoing Webhooks section of Account Settings is hidden and all outgoing webhooks are disabled.
Security note: By enabling this feature, users may be able to perform [phishing attacks](https://en.wikipedia.org/wiki/Phishing) by attempting to impersonate other users. To combat these attacks, a BOT tag appears next to all posts from a webhook. Enable at your own risk.
@@ -58,6 +63,12 @@ Maximum number of users per team, including both active and inactive users.
```"RestrictCreationToDomains": ""```
Teams can only be created by a verified email from this list of comma-separated domains (e.g. "corp.mattermost.com, mattermost.org").
+```"RestrictTeamNames": true```
+"true": Newly created team names cannot contain the following restricted words: www, web, admin, support, notify, test, demo, mail, team, channel, internal, localhost, dockerhost, stag, post, cluster, api, oauth; “false”: Newly created team names are not restricted.
+
+```"EnableTeamListing": false```
+"true": Teams that are configured to appear in the team directory will appear on the system main page. Teams can configure this setting from **Team Settings -> Include this team in the Team Directory**; "true": Team directory on the system main page is disabled.
+
### SQL Settings
@@ -130,9 +141,16 @@ Port of SMTP email server.
```"InviteSalt": "bjlSR4QqkXFBr7TP4oDzlfZmcNuH9YoS"```
32-character (to be randomly generated via Admin Console) salt added to signing of email invites.
-
```"PasswordResetSalt": "vZ4DcKyVVRlKHHJpexcuXzojkE5PZ5eL"```
-32-character (to be randomly generated via Admin Console) salt added to signing of password reset emails.
+32-character (to be randomly generated via Admin Console) salt added to signing of password reset emails.
+
+#### Push Notification Settings
+
+```"SendPushNotifications": false```
+"true": Your mattermsot server sends mobile push notifications to the server specified in **PushNotificationServer**; "false": Mobile push notifications are disabled.
+
+```"PushNotificationServer": ""```
+Address of the proxy server that re-sends push notifications to their respective services like APNS (Apple Push Notification Services).
### File Settings
@@ -257,19 +275,19 @@ Settings to configure account and team creation using GitLab OAuth.
“true”: Allow team creation and account signup using GitLab OAuth. To configure, input the **Secret** and **Id** credentials.
```"Secret": ""```
-Obtain this value by logging into your GitLab account. Go to Profile Settings -> Applications -> New Application, enter a Name, then enter Redirect URLs "https://<your-mattermost-url>/login/gitlab/complete" (example: https://example.com:8065/login/gitlab/complete) and "https://<your-mattermost-url>/signup/gitlab/complete".
+Obtain this value by logging into your GitLab account. Go to Profile Settings -> Applications -> New Application, enter a Name, then enter Redirect URLs `https://<your-mattermost-url>/login/gitlab/complete` (example: `https://example.com:8065/login/gitlab/complete`) and `https://<your-mattermost-url>/signup/gitlab/complete`.
```"Id": ""```
-Obtain this value by logging into your GitLab account. Go to Profile Settings -> Applications -> New Application, enter a Name, then enter Redirect URLs "https://<your-mattermost-url>/login/gitlab/complete" (example: https://example.com:8065/login/gitlab/complete) and "https://<your-mattermost-url>/signup/gitlab/complete".
+Obtain this value by logging into your GitLab account. Go to Profile Settings -> Applications -> New Application, enter a Name, then enter Redirect URLs `https://<your-mattermost-url>/login/gitlab/complete` (example: `https://example.com:8065/login/gitlab/complete`) and `https://<your-mattermost-url>/signup/gitlab/complete`.
```"AuthEndpoint": ""```
-Enter https://<your-gitlab-url>/oauth/authorize (example: https://example.com:3000/oauth/authorize). Use HTTP or HTTPS depending on how your server is configured.
+Enter `https://<your-gitlab-url>/oauth/authorize` (example: `https://example.com:3000/oauth/authorize`). Use HTTP or HTTPS depending on how your server is configured.
```"TokenEndpoint": ""```
-Enter https://<your-gitlab-url>/oauth/authorize (example: https://example.com:3000/oauth/token). Use HTTP or HTTPS depending on how your server is configured.
+Enter `https://<your-gitlab-url>/oauth/authorize` (example: `https://example.com:3000/oauth/token`). Use HTTP or HTTPS depending on how your server is configured.
```"UserApiEndpoint": ""```
-Enter https://<your-gitlab-url>/oauth/authorize (example: https://example.com:3000/api/v3/user). Use HTTP or HTTPS depending on how your server is configured.
+Enter `https://<your-gitlab-url>/oauth/authorize` (example: `https://example.com:3000/api/v3/user`). Use HTTP or HTTPS depending on how your server is configured.
## Config.json Settings Not in System Console
@@ -280,17 +298,6 @@ System Console allows an IT Admin to update settings defined in `config.json`. H
```"EnableOAuthServiceProvider": false```
”true”: Allow Mattermost to function as an OAuth provider, allowing 3rd party apps access to your user store for authentication.
-### Push Notification Settings
-
-```"ApplePushServer": ""```
-Setting for features in development.
-
-```"ApplePushCertPublic": ""```
-Setting for features in development.
-
-```"ApplePushCertPrivate": ""```
-Setting for features in development.
-
### File Settings
```"InitialFont": "luximbi.ttf"```
diff --git a/doc/install/Production-Ubuntu.md b/doc/install/Production-Ubuntu.md
index e792a551c..d6b98981c 100644
--- a/doc/install/Production-Ubuntu.md
+++ b/doc/install/Production-Ubuntu.md
@@ -24,21 +24,31 @@
* ```postgre=# \q```
1. You can exit the postgres account by typing:
* ``` exit```
+1. Allow Postgres to listen on all assigned IP Addresses
+ * ```sudo vi /etc/postgresql/9.3/main/postgresql.conf```
+ * Uncomment 'listen_addresses' and change 'localhost' to '*'
+1. Alter pg_hba.conf to allow the mattermost server to talk to the postgres database
+ * ```sudo vi /etc/postgresql/9.3/main/pg_hba.conf```
+ * Add the following line to the 'IPv4 local connections'
+ * host all all 10.10.10.2/32 md5
+1. Reload Postgres database
+ * ```sudo /etc/init.d/postgresql reload```
+
## Set up Mattermost Server
1. For the purposes of this guide we will assume this server has an IP address of 10.10.10.2
+1. For the sake of making this guide simple we located the files at `/home/ubuntu/mattermost`. In the future we will give guidance for storing under `/opt`.
+1. We have also elected to run the Mattermost Server as the `ubuntu` account for simplicity. We recommend setting up and running the service under a `mattermost` user account with limited permissions.
1. Download the latest Mattermost Server by typing:
- * ``` wget https://github.com/mattermost/platform/releases/download/v1.1.0/mattermost.tar.gz```
+ * ``` wget https://github.com/mattermost/platform/releases/download/v1.2.1/mattermost.tar.gz```
1. Unzip the Mattermost Server by typing:
* ``` tar -xvzf mattermost.tar.gz```
-1. For the sake of making this guide simple we located the files at `/home/ubuntu/mattermost`. In the future we will give guidance for storing under `/opt`.
-1. We have also elected to run the Mattermost Server as the `ubuntu` account for simplicity. We recommend setting up and running the service under a `mattermost` user account with limited permissions.
1. Create the storage directory for files. We assume you will have attached a large drive for storage of images and files. For this setup we will assume the directory is located at `/mattermost/data`.
* Create the directory by typing:
* ``` sudo mkdir -p /mattermost/data```
* Set the ubuntu account as the directory owner by typing:
* ``` sudo chown -R ubuntu /mattermost```
-1. Configure Mattermost Server by editing the config.json file at /home/ubuntu/mattermost/config`
+1. Configure Mattermost Server by editing the config.json file at `/home/ubuntu/mattermost/config`
* ``` cd ~/mattermost/config```
* Edit the file by typing:
* ``` vi config.json```
diff --git a/doc/install/Requirements.md b/doc/install/Requirements.md
index b877b6dc0..162caf90d 100644
--- a/doc/install/Requirements.md
+++ b/doc/install/Requirements.md
@@ -4,10 +4,10 @@
Supported Operating Systems and Browsers for the Mattermost Web Client include:
-- PC: Windows 7, Windows 8 (Chrome 43+, Firefox 38+, Internet Explorer 10+)
-- Mac: OS 10 (Safari 7, Chrome 43+)
+- PC: Windows 7, Windows 8, Windows 10 (Chrome 43+, Firefox 38+, Internet Explorer 11, Edge)
+- Mac: OS 10 (Safari 9, Chrome 43+)
- Linux: Arch 4.0.0 (Chrome 43+)
-- iPhone 4s and higher (Safari on iOS 8.3+, Chrome 43+)
+- iPhone 4s and higher (Safari on iOS 9+, Chrome 43+)
- Android 5 and higher (Chrome 43+)
### Email Client
diff --git a/doc/install/Troubleshooting.md b/doc/install/Troubleshooting.md
index 51699a39c..deae7717d 100644
--- a/doc/install/Troubleshooting.md
+++ b/doc/install/Troubleshooting.md
@@ -12,7 +12,7 @@
- If the System Administrator account becomes unavailable, a person leaving the organization for example, you can set a new system admin from the commandline using `./platform -assign_role -team_name="yourteam" -email="you@example.com" -role="system_admin"`.
- After assigning the role the user needs to log out and log back in before the System Administrator role is applied.
-#### Error Messages
+#### Mattermost Error Messages
The following is a list of common error messages and solutions:
@@ -22,15 +22,45 @@ The following is a list of common error messages and solutions:
###### `x509: certificate signed by unknown authority` in server logs when attempting to sign-up
- - This error may appear when attempt to use a self-signed certificate to setup SSL, which is not yet supported by Mattermost. You
+ - This error may appear when attempt to use a self-signed certificate to setup SSL, which is not yet supported by Mattermost.
- **Solution:** Set up a load balancer like Ngnix [per production install guide](https://github.com/mattermost/platform/blob/master/doc/install/Production-Ubuntu.md#set-up-nginx-with-ssl-recommended). A ticket exists to [add support for self-signed certificates in future](x509: certificate signed by unknown authority).
###### `panic: runtime error: invalid memory address or nil pointer dereference`
- This error can occur if you have manually manipulated the Mattermost database, typically with deletions. Mattermost is designed to serve as a searchable archive, and manual manipulation of the database elements compromises integrity and may prevent upgrade.
- **Solution:** Restore from database backup created prior to manual database updates, or reinstall the system.
+### Troubleshooting GitLab Mattermost
+
+- If you're having issues installing GitLab Mattermost with GitLab Omnibus, as a first step please turn on logging by updating the [log settings](https://github.com/mattermost/platform/blob/master/doc/install/Configuration-Settings.md#log-file-settings) section in your `config.json` file installed by omnibus, and they try a general web search for the error message you receive.
+
+#### 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](https://github.com/mattermost/platform/blob/master/doc/install/Upgrade-Guide.md), you may be able to restore Mattermost using the following procedure:
+ - `sudo stop mattermost`, so DB can be dropped
+ - `sudo gitlab-ctl reconfigure`
+ - `sudo -u gitlab-psql /opt/gitlab/embedded/bin/dropdb -h /var/opt/gitlab/postgresql mattermost_production`
+ - `sudo start mattermost`
+ - `sudo gitlab-ctl reconfigure`
+ - [Manually set up GitLab SSO](https://github.com/mattermost/platform/blob/master/doc/integrations/Single-Sign-On/Gitlab.md) by copying Secret and ID into `/var/opt/gitlab/mattermost/config.json`
+ - `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](https://github.com/mattermost/platform/blob/master/doc/integrations/Single-Sign-On/Gitlab.md) 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.
+
+###### `We couldn't find the existing account`
+ - This error appears when a user attempts to sign in using a single-sign-on option with an account that was not created using that single-sign-on option. For example, if a user creates Account A using email sign-up, then attempts to sign-in using GitLab SSO, the error appears since Account A was not created using GitLab SSO.
+ - **Solution:**
+ - If you're switching from email auth to GitLab SSO, and you're getting this issue on an admin account, consider deactivating your email-based account, then creating a new account with System Admin privileges using GitLab SSO. Specifically:
+ 1. Deactivate your email-based System Admin account (note: this process is [scheduled to improve](https://mattermost.atlassian.net/browse/PLT-975))
+ 1. Temporarily turn off email verification (**System Console** > **Email Settings** > **Require Email Verification** > **false**, or set `"RequireEmailVerification": false` in `config.json`).
+ 2. Change email for account to random address so you can create a new GitLab SSO account using your regular address.
+ 2. Create a new Mattermost account using GitLab SSO
+ 1. With GitLab SSO enabled, go to `https://domain.com/teamname` and sign-up for a new Mattermost account using your GitLab SSO account with preferred email address.
+ 2. [Upgrade the new account to System Admin privileges](https://github.com/mattermost/platform/blob/master/doc/install/Troubleshooting.md#lost-system-administrator-account).
+ 3. Deactivate the previous System Admin account that used email authentication.
+ 1. Using the new GitLab SSO System Admin account go to **System Console** > **[TEAMNAME]** > **Users**, find the previous account and set it to "Inactive"
diff --git a/doc/install/Upgrade-Guide.md b/doc/install/Upgrade-Guide.md
index 7f4eeaeb9..edcc754f8 100644
--- a/doc/install/Upgrade-Guide.md
+++ b/doc/install/Upgrade-Guide.md
@@ -4,6 +4,8 @@
Each release of Mattermost contains logic to upgrade it from the previously major build version. For example, version 1.2 upgrades the database and configuration data schema for a Mattermost version 1.1 server. The following procedure outlines how to upgrade Mattermost to the next major release version.
+If you're upgrading across multiple major releases, from 1.0.x to 1.2.x for example, please run the following procedure once for each incremental upgrade, in sequential order.
+
1. Download the **next major build release** of your server
1. Determine the current version of your Mattermost server
1. Go to any team site, opening the main menu at the top right of the left-hand sidebar and selecting **About Mattermost**
@@ -11,9 +13,9 @@ Each release of Mattermost contains logic to upgrade it from the previously majo
1. For example, if your current version is 1.1.0, you want to select version 1.2.0.
1. In some cases there will be **minor build releases**, such as 1.2.1 and 1.2.2. The minor build number indicates a bug fix or security issue release. Testing on minor build versions is less extensive than on major build versions and it is recommended that you use the minor build only if you need the specific additions included.
3. Review Release Notes
- 1. Check the release notes for the version of Mattermost you are able to install, and note any setting changes in the **Compatibility** section that apply to your deployment
+ 1. Check the release notes for the version of Mattermost you are able to install, and note any setting changes in the **Compatibility** section that apply to your deployment (Release notes across versions are available from the [CHANGELOG](https://github.com/mattermost/platform/blob/master/CHANGELOG.md)).
4. Download the `mattermost.tar.gz` file with the correct version for your upgrade
- 1. You can use `wget` to retrieve a specific version. For example, to download v1.1.0 run `wget https://github.com/mattermost/platform/releases/download/v1.1.0/mattermost.tar.gz`
+ 1. You can use `wget` to retrieve a specific version. For example, to download v1.1.0 run `wget https://github.com/mattermost/platform/releases/download/v1.x.x/mattermost.tar.gz`
2. Stop the Mattermost Server
1. As best practice, consider posting to the Town Square channel of active teams pre-announcing the scheduled downtime to apply these upgrade procedures
2. To stop the server run `sudo stop mattermost`
@@ -26,9 +28,9 @@ Each release of Mattermost contains logic to upgrade it from the previously majo
5. Restore the state of your server by copying the backed up version of `config.json` in place of the default `config.json`
6. Start your server and address any setting changes relevant in the latest version of Mattermost
1. Run `sudo start mattermost`
- 2. The server will upgrade your database schema to be compatibile with the new release, as well as upgrade your `config.json` file to the latest format, using default values for new settings added
- 3. Go to the System Console to update any settings that have been added or modified based on the **Compatibility** documentation in the release notes
-7. Test the system is working by going to the URL of an existing team
+ 2. Go to the **System Console** to update any settings that have been added or modified based on the **Compatibility** section in the release notes of the version you are installing (Release notes across versions are available from the [CHANGELOG](https://github.com/mattermost/platform/blob/master/CHANGELOG.md)).
+ 1. Opening the System Console and saving a change will upgrade your `config.json` schema to the latest version using default values for new settings added
+7. Test the system is working by going to the URL of an existing team. You may need to refresh your Mattermost browser page in order to get the latest updates from the upgrade
### Upgrading from Mattermost Beta (Version 0.7)
generated by cgit v1.2.3-1-g7c22 (git 2.25.1) at 2024-07-24 04:24:19 +0000