Skip to content

Update Troubleshooting.md #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 14, 2016
Merged

Update Troubleshooting.md #2

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 36 additions & 13 deletions source/install/Troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,22 @@
- 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="[email protected]" -role="system_admin"`.
- After assigning the role the user needs to log out and log back in before the System Administrator role is applied.

##### Switching System Administrator Account to SSO Sign-in

When Mattermost is initially set up, the first account created becomes the System Administrator account. This account will typically use email authentication to sign-in, since it is usually created before other sign-in methods are configured.

After setting up SSO authentication, it is common for the System Administrator to want to turn off email sign-in so users will only have SSO as a sign-in option.

Before doing this, the System Administrator needs to change their sign-in method to SSO by doing the following:
1. Sign in to Mattermost using email and password
2. Go to Account Settings > Security > Sign-in Method
3. Click the "Switch" button for the sign in method you would like to use, and complete the process for switching sign-in method.

The System Administrator can now turn off email sign-in and still access their account. (To avoid locking other existing users out of their accounts, it is recommended the System Administrator ask them to switch authentication methods as well.)

##### Locked out of System Administrator account
If email sign-in was turned off before the System Administrator switched sign-in methods, sign up for a new account and promote it to System Administrator from the command line.

#### Mattermost Error Messages

The following is a list of common error messages and solutions:
Expand All @@ -29,6 +45,26 @@ The following is a list of common error messages and solutions:
- 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.

###### `We couldn't find an existing account matching your email address for this team. This team may require an invite from the team owner to join.`
- This error appears when a user tries to sign in, and Mattermost can't find an account matching the credentials they entered.
- **Solution:**

1. **If you're signing in with email and have previously created an account:**
1. Check that you are using the correct email address. If you can't remember what email address was used, contact the System Administrator for assistance.

2. **If you haven't signed up for an account on this team yet:**
1. Click the link at the bottom of the sign-in page that says “Don't have an account? Create one now” to create an account. If the link is not available, contact a Team or System Administrator for an invitation.

3. **If your account uses a different sign-in method** (for example, the account was created with email but the user is trying to use SSO to sign in):
1. Check the sign-in page.
2. If the sign-in method the account was created with is available, use that to sign in.
- *Note: You may then switch authentication methods from Account Settings > Security > Sign-in Method.*
3. If the sign-in method is not available, contact the System Administrator.
- This can happen if the site was originally set up to allow an account to be created using either GitLab or Email, but then the System Administrator turned one of the options off.
- The System Administrator can fix this issue by:
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.

### 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.
Expand All @@ -51,16 +87,3 @@ The following is a list of common error messages and solutions:
- **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"