diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.md | 21 | ||||
| -rw-r--r-- | doc/developer/API.md | 2 | ||||
| -rw-r--r-- | doc/developer/tests/test-link-preview.md | 23 | ||||
| -rw-r--r-- | doc/developer/tests/test-links.md | 16 | ||||
| -rw-r--r-- | doc/developer/tests/test-markdown.md | 14 | ||||
| -rw-r--r-- | doc/developer/tests/test-mentions.md | 13 | ||||
| -rw-r--r-- | doc/help/Messaging.md | 34 | ||||
| -rw-r--r-- | doc/help/README.md | 12 | ||||
| -rw-r--r-- | doc/help/Sign-in.md | 19 | ||||
| -rw-r--r-- | doc/help/Slack-Import.md | 29 | ||||
| -rw-r--r-- | doc/help/Team-Settings.md | 70 | ||||
| -rw-r--r-- | doc/help/Team-Statistics.md | 24 | ||||
| -rw-r--r-- | doc/help/system-console/Team-Statistics.md | 24 | ||||
| -rw-r--r-- | doc/install/Administration.md | 65 | ||||
| -rw-r--r-- | doc/install/Production-Ubuntu.md | 10 | ||||
| -rw-r--r-- | doc/install/Troubleshooting.md | 32 | ||||
| -rw-r--r-- | doc/integrations/webhooks/Incoming-Webhooks.md | 27 | ||||
| -rw-r--r-- | doc/process/documentation-guidelines.md | 29 |
18 files changed, 376 insertions, 88 deletions
diff --git a/doc/README.md b/doc/README.md index 7ed20fba6..d062dee65 100644 --- a/doc/README.md +++ b/doc/README.md @@ -53,11 +53,20 @@ Procedures for upgrading the Mattermost server _Note: End user help documentation is a new feature being completed for the v1.2 release. The materials below are work in progress._ -- User Interface - - [Manage Members](help/Manage-Members.md) - - Team Settings - - [Slack Import](help/Slack-Import.md) +- Getting Started + - [Sign-in](help/Sign-in.md) -- Messaging - - [Mattermost Markdown Formatting](usage/Markdown.md) +- User Interface + - Main Menu + - [Team Settings ](https://github.com/mattermost/platform/blob/help-docs-update/doc/help/Team-Settings.md) + - [General Settings](https://github.com/mattermost/platform/blob/help-docs-update/doc/help/Team-Settings.md#general) + - [Slack Import](https://github.com/mattermost/platform/blob/help-docs-update/doc/help/Team-Settings.md#import-from-slack-beta) + - [Manage Members](help/Manage-Members.md) + - Messaging + - [Mattermost Markdown Formatting](usage/Markdown.md) + - [Search](help/Search.md) + +- System Console + - Team + - [Team Statistics](help/system-console/Team-Statistics.md) diff --git a/doc/developer/API.md b/doc/developer/API.md index 4c4b2f04e..e5e5db2ba 100644 --- a/doc/developer/API.md +++ b/doc/developer/API.md @@ -12,7 +12,7 @@ Incoming webhooks allow external applications to post messages into Mattermost c In addition to supporting Slack's incoming webhook formatting, Mattermost webhooks offer full support of industry-standard markdown formatting, including headings, tables and in-line images. -### [Outgoing Webhooks (in Mattermost v1.2)](https://github.com/mattermost/platform/blob/master/doc/integrations/webhooks/Outgoing-Webhooks.md) +### [Outgoing Webhooks](https://github.com/mattermost/platform/blob/master/doc/integrations/webhooks/Outgoing-Webhooks.md) Outgoing webhooks allow external applications to receive webhook events from events happening within Mattermost channels and private groups via JSON payloads via HTTP POST requests sent to incoming webhook URLs defined by your applications. diff --git a/doc/developer/tests/test-link-preview.md b/doc/developer/tests/test-link-preview.md new file mode 100644 index 000000000..4061bda35 --- /dev/null +++ b/doc/developer/tests/test-link-preview.md @@ -0,0 +1,23 @@ +# Link Preview Tests + +Link previews should embed previews of the contents of a hyperlink from a message or comment in the center channel directly below the message or comment. + +Post location variation: + +1. Post as message in center channel with RHS closed (link preview should render under message) +2. Post as message in center channel with RHS open (link preview should render under message) +3. Post as comment in RHS (link preview should not render) +4. View comment in center channel with RHS closed (link preview should render under message) +5. View comment in center channel with RHS open (link preview should render under message) +6. Search for post in RHS with link + +Post the following links one per message in the above variations: + +Twitter Link Preview: +https://twitter.com/mattermosthq/status/664928489078820865 + +Vine: +https://vine.co/v/eDeVgbFrt9L + +Wikipedia +https://en.wikipedia.org/wiki/Princess_Bubblegum diff --git a/doc/developer/tests/test-links.md b/doc/developer/tests/test-links.md new file mode 100644 index 000000000..62b729b30 --- /dev/null +++ b/doc/developer/tests/test-links.md @@ -0,0 +1,16 @@ + +# Link Testing + +Links in Mattermosts should render as specified below. Paste the below text into Mattermost to test text processing. + +``` +These strings should auto-link: + +http://wikipedia.com +https://wikipedia.com +www.wikipedia.com + +These strings should not auto-link: + +Readme.md +``` diff --git a/doc/developer/tests/test-markdown.md b/doc/developer/tests/test-markdown.md new file mode 100644 index 000000000..8a24aad86 --- /dev/null +++ b/doc/developer/tests/test-markdown.md @@ -0,0 +1,14 @@ +# Markdown tests + +Paste the following tests into Mattermost to test markdown support. + +``` +# This should render as Heading 1 font size +## This should render as Heading 2 font size +### This should render as Heading 3 font size +#### This should render as Heading 4 font size +##### This should render as Heading 5 font size +###### This should render as Heading 6 font size +~~This should show strikethrough formatting~~ +**This should be bold** +``` diff --git a/doc/developer/tests/test-mentions.md b/doc/developer/tests/test-mentions.md new file mode 100644 index 000000000..99a47e337 --- /dev/null +++ b/doc/developer/tests/test-mentions.md @@ -0,0 +1,13 @@ +# Mentions Testing + +To test the following mention functional: + +1. Add a user 'alice' to the system +2. Paste the below text to test if mentions is properly highlighting + + +``` +To run this test, if a user named @alice doesn't yet exist, create one. + +I saw @alice--and I said "Hi @alice!" then "What's up @alice?" and then @alice, was totally @alice; she just "@alice"'d me and walked on by. That's @alice... +``` diff --git a/doc/help/Messaging.md b/doc/help/Messaging.md new file mode 100644 index 000000000..03adc1ce8 --- /dev/null +++ b/doc/help/Messaging.md @@ -0,0 +1,34 @@ +# Messaging + +## Writing Messages + +You can write messages using the input box with the text "Write a message..." at the bottom of Mattermost. + +Press **ENTER** to send a message. Use **Ctrl+ENTER** to create a new line without sending a message. + +## Formatting Messages + +Mattermost messages are formatted using a standard called "markdown". Here are examples: + +| Text Entered | How it appears | +|:---------------|:---------------| +|`**bold**`| **bold** | +| `_italic_`|_italic_| +|`[hyperlink](http://mattermost.org)`|[hyperlink](http://mattermost.org)| +|``|| + +## Mentioning Teammates + +You can mention a teammate by using the `@` symbol plus their username to send them a special notification to draw their attention. + +For example, you might write: + +``` +@alice how did your interview go with the new candidate? +``` + +Which sends a special mention notification to **alice** to check your message. + +To mention a teammate, press `@` and you should see a list of team members who can be messaged. You can either type their username or use the **Up** and **Down** arrow keys and then **ENTER** to select them to be mentioned. + +You can configure how you'd like to be alerted about mentions of your username, your first name, your nickname, or other keywords from **Account Settings** > **Notifications** and you can set channel-specific preferences from **[Channel Name]** > **Notification Preferences** diff --git a/doc/help/README.md b/doc/help/README.md deleted file mode 100644 index 9271d64dd..000000000 --- a/doc/help/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# Help - -The help section of the Mattermost documentation is intended for use by end users learning about the Mattermost concepts, usage, terminology and user interface. - -_Note: Help documentation is a work-in-progress. Community contributions highly welcome. Please see [guidelines for contributing](https://forum.mattermost.org/t/help-improve-mattermost-documentation/194)._ - -## Team Site Main Menu - -You can access the **Team Site Main Menu** by clicking on the three vertical dots at the top of the left sidebar in a team site. Here we describe the various options available from the menu: - -- [Manage Members](Manage-Members.md) - diff --git a/doc/help/Sign-in.md b/doc/help/Sign-in.md new file mode 100644 index 000000000..728a7d42c --- /dev/null +++ b/doc/help/Sign-in.md @@ -0,0 +1,19 @@ +# Sign-in + +You can sign-in to your team from the web address of `https://domain.com/teamname`. + +There are several options for signing in depending on how your System Administrator has configured your server. + +#### Email address and password sign-in + +If available, you can sign in using the combination of email address and password used to create your account. + +If you have forgotten your password, you should be able to reset it from the "I forgot my password" option on the sign-in screen, or contact your System Administrator if you need help resetting your password. + +#### GitLab Single-Sign-On (SSO) option + +If available, you can sign in using your GitLab account using a one-click sign-in option. GitLab SSO lets you create teams, create accounts on teams, and sign-in to teams using one username, email address and password that works across everything on the server. + +#### Switching Teams + +You can switch among teams you've recently signed into using the main menu in any team site on the server. By default, devices remember which teams you have signed into for 30 days, and this duration is configurable by the System Administrator. diff --git a/doc/help/Slack-Import.md b/doc/help/Slack-Import.md deleted file mode 100644 index f834d5177..000000000 --- a/doc/help/Slack-Import.md +++ /dev/null @@ -1,29 +0,0 @@ -### Slack Import - -*Note: As a proprietary SaaS service, Slack is able to change its export format quickly and without notice. If you encounter issues not mentioned in the documentation below, please alert the product team by [filing an issue](https://github.com/mattermost/platform/issues).* - -#### Usage - -The Slack Import feature in Mattermost is in "Beta" and focus is on supporting migration of teams of less than 100 registered users. To use: - -1. Generate a Slack "Export" file from **Slack > Team Settings > Import/Export Data > Export > Start Export** - -2. In Mattermost go to **Team Settings > Import > Import from Slack**. _Team Owner_ or _Team Administrator_ role is required to access this menu option. - -3. Click **Select file** to upload Slack export file and click **Import**. - -4. Emails and usernames from Slack are used to create new Mattermost accounts - -5. Slack users can activate their new Mattermost accounts by using Mattermost's Password Reset screen with their email addresses from Slack to set new passwords for their Mattermost accounts - -6. Once logged in, the Mattermost users will have access to previous Slack messages in the public channels imported from Slack. - -**It is highly recommended that you test Slack import before applying it to an instance intended for production.** If you use Docker, you can spin up a test instance in one line (`docker run --name mattermost-dev -d --publish 8065:80 mattermost/platform`). If you don't use Docker, there are [step-by-step instructions](../install/Docker-Single-Container.md) to install Mattermost in preview mode in less than 5 minutes. - -#### Notes: - -- Newly added markdown suppport in Slack's Posts 2.0 feature announced on September 28, 2015 is not yet supported. -- Slack does not export files or images your team has stored in Slack's database. Mattermost will provide links to the location of your assets in Slack's web UI. -- Slack does not export any content from private groups or direct messages that your team has stored in Slack's database. -- In Beta, Slack accounts with username or email address collisions with existing Mattermost accounts will not import and mentions do not resolve as Mattermost usernames (still shows Slack ID). No pre-check or roll-back is currently offered. - diff --git a/doc/help/Team-Settings.md b/doc/help/Team-Settings.md new file mode 100644 index 000000000..7e6cf5dd5 --- /dev/null +++ b/doc/help/Team-Settings.md @@ -0,0 +1,70 @@ +## Team Settings + +The Team Settings menu offers Team Administrators, Team Owners and System Administrators to adjust settings applying to a specific team. + +The following settings are found in a Team Site from the **Three-Dot** menu at the top of the left sidebar under **Team Settings**. + +### General + +General settings under the **Team Settings** > **General** configure how a team is displayed to users. + +#### Team Name + +Your **Team Name** is displayed on the sign-in page, and in the top of the left-hand sidebar for your team. + +#### Allow anyone to sign-up from login page + +Setting this option to **Yes** a link to the account creation page is included on the sign-in page of this team. + +Team Administrators would set this to **Yes** when they: + 1. Operate on a closed network and want to make sign-up easy. + 2. Operate on the open internet with sign-up restricted to specific domains, and want to allow easy sign-up from users with email addresses. Note: System Administrators can restrict sign-up to specific domains via the System Console. + 3. Operate on the open internet and want to allow anyone to sign-up. + +Team Administrators would set this to **No** when they: + 1. Operate on the open internet and want a small, private team that is email-invite-only + +#### Include this team in the Team Directory + +Setting this option to **Yes** includes the Team Name on the Home Page and a link to this team's sign-in page. + +Team Administrators would set this to **Yes** when they: + 1. Operate on a closed network and want to make it easy to discover their team from the Home Page of the Mattermost server. + 2. Operate on the open internet with sign-up restricted to specific domains, and want to allow easy sign-up from users with email addresses. Note: System Administrators can restrict sign-up to specific domains via the System Console. + 3. Operate on the open internet and want to allow anyone to sign-up to their team from the Home Page of the Mattermost server. + +Team Administrators would set this to **No** when they: + 1. Operate on the open internet and want a small, private team that is email-invite-only + +#### Invite Code + +When allowing anyone to sign-up from the login page, the **Invite Code** is used as part of the sign-up process. Clicking **Re-Generate** will invalidate the previous invitations and invitation URLs. + +### Import + +#### Import from Slack (Beta) + +*Note: As a proprietary SaaS service, Slack is able to change its export format quickly and without notice. If you encounter issues not mentioned in the documentation below, please alert the product team by [filing an issue](https://github.com/mattermost/platform/issues).* + +The Slack Import feature in Mattermost is in "Beta" and focus is on supporting migration of teams of less than 100 registered users. To use: + +1. Generate a Slack "Export" file from **Slack > Team Settings > Import/Export Data > Export > Start Export** + +2. In Mattermost go to **Team Settings > Import > Import from Slack**. _Team Owner_ or _Team Administrator_ role is required to access this menu option. + +3. Click **Select file** to upload Slack export file and click **Import**. + +4. Emails and usernames from Slack are used to create new Mattermost accounts + +5. Slack users can activate their new Mattermost accounts by using Mattermost's Password Reset screen with their email addresses from Slack to set new passwords for their Mattermost accounts + +6. Once logged in, the Mattermost users will have access to previous Slack messages in the public channels imported from Slack. + +**It is highly recommended that you test Slack import before applying it to an instance intended for production.** If you use Docker, you can spin up a test instance in one line (`docker run --name mattermost-dev -d --publish 8065:80 mattermost/platform`). If you don't use Docker, there are [step-by-step instructions](../install/Docker-Single-Container.md) to install Mattermost in preview mode in less than 5 minutes. + +#### Notes: + +- Newly added markdown suppport in Slack's Posts 2.0 feature announced on September 28, 2015 is not yet supported. +- Slack does not export files or images your team has stored in Slack's database. Mattermost will provide links to the location of your assets in Slack's web UI. +- Slack does not export any content from private groups or direct messages that your team has stored in Slack's database. +- In Beta, Slack accounts with username or email address collisions with existing Mattermost accounts will not import and mentions do not resolve as Mattermost usernames (still shows Slack ID). No pre-check or roll-back is currently offered. diff --git a/doc/help/Team-Statistics.md b/doc/help/Team-Statistics.md deleted file mode 100644 index 05d63794b..000000000 --- a/doc/help/Team-Statistics.md +++ /dev/null @@ -1,24 +0,0 @@ -## Team Statistics -___ -Statistics on users, posts and channels are tracked for each team and viewable in the System Console. System Administrators can access statistics for your Mattermost teams by clicking the **three-dot menu**, then click **System Console**. Under the *Teams* section on the left side you’ll see a list of the teams that belong to your domain. Click **Statistics** under the team of interest to open the stats page. Here is some helpful terminology: - -**Total Users** -The total number of accounts created, regardless of if the accounts are active or inactive. - -**Total Posts** -The total number of posts made by your team, including deleted posts or those made by incoming and outgoing webhook integrations. - -**Public Groups** -The number of public channels created by your team, including channels that may have been archived. - -**Private Group** -The number of private groups created by your team, including groups that may have been archived. - -**Active Users With Posts** -Users who logged in and made a post on a certain day. - -**Recently Active Users** -Users that have logged in and had recent browser activity in Mattermost. - -**Newly Created Users** -Users that have recently completed the signup process to create a Mattermost account on the team. diff --git a/doc/help/system-console/Team-Statistics.md b/doc/help/system-console/Team-Statistics.md new file mode 100644 index 000000000..eef7b8346 --- /dev/null +++ b/doc/help/system-console/Team-Statistics.md @@ -0,0 +1,24 @@ +# Team Statistics + +Statistics on users, posts and channels are tracked for each team are viewable under **System Console** > **Teams** > **Statistics**. + +## Total Users +The total number of accounts created, including both active and inactive accounts. + +## Total Posts +The total number of posts made in a team, including deleted posts and posts made using automation. + +## Public Groups +The number of public channels created by your team, including channels that may have been archived. + +## Private Group +The number of private groups created by your team, including groups that may have been archived. + +## Active Users With Posts +Users who logged in and made a post on a certain day. + +## Recently Active Users +Users that have logged in and had recent browser activity in Mattermost. + +## Newly Created Users +Users that have recently completed the sign-up process to create a Mattermost account on the team. diff --git a/doc/install/Administration.md b/doc/install/Administration.md index ee996088c..76ec78abd 100644 --- a/doc/install/Administration.md +++ b/doc/install/Administration.md @@ -17,3 +17,68 @@ 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: + +- [GitLab Mattermost discussion forum](https://forum.mattermost.org/c/general/gitlab) +- [GitLab Mattermost issue tracker on GitLab.com](https://gitlab.com/gitlab-org/gitlab-mattermost/issues) + +### Setting up realtime notifications from GitLab to Mattermost + +To set up standard notification from GitLab to Mattermost [follow these steps](https://github.com/mattermost/platform/blob/master/doc/integrations/webhooks/Incoming-Webhooks.md#connecting-mattermost-to-gitlab-using-slack-ui). + +To set up a set of fully customizable realtime notifications from GitLab to Mattermost you can run the [GitLab Integration Service for Mattermost](https://github.com/mattermost/mattermost-integration-gitlab). + +### 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. + +###### `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/Production-Ubuntu.md b/doc/install/Production-Ubuntu.md index e792a551c..098707ada 100644 --- a/doc/install/Production-Ubuntu.md +++ b/doc/install/Production-Ubuntu.md @@ -24,6 +24,16 @@ * ```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 diff --git a/doc/install/Troubleshooting.md b/doc/install/Troubleshooting.md index 51699a39c..78ab5617d 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: @@ -29,8 +29,38 @@ 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. +### 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/integrations/webhooks/Incoming-Webhooks.md b/doc/integrations/webhooks/Incoming-Webhooks.md index b5ae0fde2..5e93c4ac7 100644 --- a/doc/integrations/webhooks/Incoming-Webhooks.md +++ b/doc/integrations/webhooks/Incoming-Webhooks.md @@ -81,18 +81,27 @@ Additional Notes: ### Slack Compatibility -As mentioned above, Mattermost makes it easy to take integrations written for Slack's proprietary JSON payload format and repurpose them to become Mattermost integrations. The following automatic translations are supported: +Mattermost makes it easy to take integrations written for Slack's proprietary JSON payload format and repurpose them to become Mattermost integrations. For example: + +#### Connecting Mattermost to GitLab using Slack UI + +GitLab is the leading open-source alternative to GitHub and offers built-in integrations with Slack. Rather than having to change code to support Mattermost, users can add Mattermost webhooks directly into the interface for Slack. + +1. In GitLab, go to **Settings** > **Services** and select **Slack**. +2. Paste in the incoming webhook URL provided by Mattermost from under **Account Settings** > **Integration** > **Incoming Webhooks**. +3. Optionally set the **Username** you'd like displayed when the notification is made. Leave the **Channel** field blank +4. Click **Save** then test the settings to confirm posts will be made to Mattermost + +#### Translating Slack's proprietary data format to Mattermost + +The following describes the automatic translations Mattermost performance to process data coming from Slack: 1. Payloads designed for Slack using `<>` to note the need to hyperlink a URL, such as ```payload={"text": "<http://www.mattermost.com/>"}```, are translated to the equivalent markdown in Mattermost and rendered the same as you would see in Slack 2. Similiarly, payloads designed for Slack using `|` within a `<>` to define linked text, such as ```payload={"text": "Click <http://www.mattermost.com/|here> for a link."}```, are also translated to the equivalent markdown in Mattermost and rendered the same as you would see in Slack -3. Like Slack, by overriding the channel name with an @username, such as payload={"text": "Hi", channel: "@jim"}, you can send the message to a user through your direct message chat -4. Channel names can be prepended with a #, like they are in Slack incoming webhooks, and the message will still be sent to the correct channel +3. Like Slack, by overriding the channel name with a `@username`, such as `payload={"text": "Hi", channel: "@jim"}`, you can send the message to a user through your direct message chat +4. Channel names can be prepended with a `#`, like they are in Slack incoming webhooks, and the message will still be sent to the correct channel To see samples and community contributions, please visit <http://mattermost.org/webhooks>. -#### Known Issues in v1.1 - -- The `attachments` payload used in Slack is not yet supported -- Overriding of usernames does not yet apply to notifications (fixed on master) -- Cannot supply `icon_emoji` to override the message icon -- Webhook UI fails when connected to deleted channel (fixed on master) +#### Known Issues +- Mattermost does not yet support Slack's feature of using _icon_emoji_ to override the message icon. diff --git a/doc/process/documentation-guidelines.md b/doc/process/documentation-guidelines.md index 59ed0a445..e75bb3169 100644 --- a/doc/process/documentation-guidelines.md +++ b/doc/process/documentation-guidelines.md @@ -41,7 +41,7 @@ This procedure works on Linux servers running Python 2.6 and higher. ### Use headings -Headings in markdown provide anchors that can be used to easily reference sub-sections of long pieces of documentation. This is preferrable to just numbering sections without headings. +Headings in markdown provide anchors that can be used to easily reference sub-sections of long pieces of documentation. This is preferable to just numbering sections without headings. ##### Correct: @@ -77,7 +77,24 @@ H3, H4, H5 headings should be "Sentence case" and can be any length. These headers are smaller and used to summarize sections. H3 can be considered either a large or small heading. -These conventions are new, so there's flexibility around them, when you're not sure, consider the convention here as default. +These conventions are new, so there's flexibility around them, when you're not sure, consider the convention here as default. + +### Sub-section headings should end with a colon + +For readability and clear layout, end a sub-section heading with a colon + +##### Correct: + +---- +Service Based: +- [AWS Elastic Beanstalk Setup](https://github.com/mattermost/platform/blob/master/doc/install/Amazon-Elastic-Beanstalk.md) +---- +##### Incorrect: + +---- +Optional +- [Community Guide for Production Debian Setup](https://github.com/mattermost/platform/blob/master/doc/install/Production-Debian.md) +---- ### One instruction per line @@ -102,20 +119,20 @@ A support person should be able to say "Did you complete step 7?" instead of "Di ---- -### Lists end without periods +### End Lists Consistently -Sentences within bullet points or numbered lists should end in normal punctuation. The sentence or fragment at the end of a bullet point should not have a period. +Full sentences in lists should end with proper punctuation. If one point in a bulleted list or numbered list ends with a period, end all points in the list with a period. If all points in the list are fragments, use no end punctuation. ##### Correct ---- -- This is a sentence within a bullet point. This is the end of a bullet point without a period +- This is an example of a bullet point that ends with a period. ---- ##### Incorrect ---- -- This is an incorrect ending of a bullet point with a period. +- Example of an incorrect period at the end of a bullet point. ---- ### Avoid Passive Phrases |