summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/README.md4
-rw-r--r--doc/api/Overview.md2
-rw-r--r--doc/developer/Code-Contribution-Guidelines.md10
-rw-r--r--doc/developer/Setup.md4
-rw-r--r--doc/help/Manage-Members.md (renamed from doc/help/Manage-Team.md)8
-rw-r--r--doc/help/README.md2
-rw-r--r--doc/help/Slack-Import.md16
-rw-r--r--doc/install/Configuration-Settings.md302
-rw-r--r--doc/install/Release-Numbering.md2
-rw-r--r--doc/install/SMTP-Email-Setup.md14
-rw-r--r--doc/install/Troubleshooting.md7
-rw-r--r--doc/integrations/Single-Sign-On/Gitlab.md12
-rw-r--r--doc/integrations/webhooks/Incoming-Webhooks.md68
13 files changed, 397 insertions, 54 deletions
diff --git a/doc/README.md b/doc/README.md
index f106cdfc8..7ee2bb46c 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -26,14 +26,14 @@ Set up Mattermost in your data center
- [Developer Machine Setup](developer/Setup.md)
- [Mattermost Style Guide](developer/Style-Guide.md)
- [API Overview](api/Overview.md)
- - [Incoming Webhooks](integrations/webhooks/Incoming.md)
+ - [Incoming Webhooks](integrations/webhooks/Incoming-Webhooks.md)
## Help
_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 Team](help/Manage-Team.md)
+ - [Manage Members](help/Manage-Members.md)
- Team Settings
- [Slack Import](help/Slack-Import.md)
diff --git a/doc/api/Overview.md b/doc/api/Overview.md
index 02e11974e..0a407b1e9 100644
--- a/doc/api/Overview.md
+++ b/doc/api/Overview.md
@@ -77,7 +77,7 @@ X-Ratelimit-Reset: 1441983590
These headers are telling you your current rate limit status.
Header | Description
---------------------- | -----------
+:--------------------- |:-----------
X-Ratelimit-Limit | The maximum number of requests you can make per second.
X-Ratelimit-Remaining | The number of requests remaining in the current window.
X-Ratelimit-Reset | The remaining UTC epoch seconds before the rate limit resets.
diff --git a/doc/developer/Code-Contribution-Guidelines.md b/doc/developer/Code-Contribution-Guidelines.md
index 80676f107..48bbf2491 100644
--- a/doc/developer/Code-Contribution-Guidelines.md
+++ b/doc/developer/Code-Contribution-Guidelines.md
@@ -5,7 +5,6 @@ Thank you for your interest in contributing to Mattermost. This guide provides a
## Choose a Ticket
1. Review the list of [Good First Contribution](https://mattermost.atlassian.net/issues/?filter=10206) tickets listed in Jira.
-
2. These projects are intended to be a straight forward first pull requests from new contributors.
If you don't find something appropriate for your interests, please see the full list of tickets [Accepting Pull Requests](https://mattermost.atlassian.net/issues/?filter=10101).
@@ -13,7 +12,7 @@ If you don't find something appropriate for your interests, please see the full
## Install Mattermost and set up a Fork
-1. Follow [developer setup instructions](https://github.com/mattermost/platform/blob/master/doc/install/dev-setup.md) to install Mattermost.
+1. Follow [developer setup instructions](https://github.com/mattermost/platform/blob/master/doc/developer/Setup.md) to install Mattermost.
2. Create a branch with <branch name> set to the ID of the ticket you're working on, for example ```PLT-394```, using command:
@@ -29,15 +28,18 @@ git checkout -b <branch name>
2. Please make sure to thoroughly test your change before submitting a pull request.
+ Please review the ["Fast, Obvious, Forgiving" experience design principles](http://www.mattermost.org/design-principles/) for Mattermost and check that your feature meets the criteria. Also, for any changes to user interface or help text, please read the changes out loud, as a quick and easy way to catch any inconsitencies.
+
+
## Submitting a Pull Request
1. Please add yourself to the Mattermost [approved contributor list](https://docs.google.com/spreadsheets/d/1NTCeG-iL_VS9bFqtmHSfwETo5f-8MQ7oMDE5IUYJi_Y/pubhtml?gid=0&single=true) prior to submitting by completing the [contributor license agreement](http://www.mattermost.org/mattermost-contributor-agreement/).
-2. When you submit your pull request please include the Ticket ID at the beginning of your pull request comment, followed by a colon.
+2. When you submit your pull request please make it against `master` and include the Ticket ID at the beginning of your pull request comment, followed by a colon.
For example, for a ticket ID `PLT-394` start your comment with: `PLT-394:`. See [previously closed pull requests](https://github.com/mattermost/platform/pulls?q=is%3Apr+is%3Aclosed) for examples.
-3. Once submitted, your pull request will be checked via an automated build process and will be reviewed by the Mattermost core team, who may either accept the PR or follow-up with feedback.
+3. Once submitted, your pull request will be checked via an automated build process and will be reviewed by at least two members of the Mattermost core team, who may either accept the PR or follow-up with feedback. It would then get merged into `master` for the next release.
4. If you've included your mailing address in Step 1, you'll be receiving a [Limited Edition Mattermost Mug](http://forum.mattermost.org/t/limited-edition-mattermost-mugs/143) as a thank you gift after your first pull request has been accepted.
diff --git a/doc/developer/Setup.md b/doc/developer/Setup.md
index c63bde512..afaef4ee4 100644
--- a/doc/developer/Setup.md
+++ b/doc/developer/Setup.md
@@ -11,7 +11,7 @@ Developer Machine Setup
`docker-machine ip dev`
3. Add a line to your /etc/hosts that goes `<Docker IP> dockerhost`
4. Run `docker-machine env dev` and copy the export statements to your ~/.bash_profile
-2. Download Go (version 1.4.2) from http://golang.org/dl/
+2. Download Go (version 1.4.2 or 1.5.1. Final release bits are built with 1.4.2) from http://golang.org/dl/
3. Set up your Go workspace
1. `mkdir ~/go`
2. Add the following to your ~/.bash_profile
@@ -51,7 +51,7 @@ Any issues? Please let us know on our forums at: http://forum.mattermost.org
`127.0.0.1 dockerhost`
3. Install build essentials
1. `apt-get install build-essential`
-4. Download Go (version 1.4.2) from http://golang.org/dl/
+4. Download Go (version 1.4.2 or 1.5.1. Final release bits are built with 1.4.2) from http://golang.org/dl/
5. Set up your Go workspace and add Go to the PATH
1. `mkdir ~/go`
2. Add the following to your ~/.bashrc
diff --git a/doc/help/Manage-Team.md b/doc/help/Manage-Members.md
index b45ea4283..04243f9fb 100644
--- a/doc/help/Manage-Team.md
+++ b/doc/help/Manage-Members.md
@@ -1,10 +1,10 @@
-# Manage Team
+# Manage Members
-The Manage Team menu is used to change the user roles assigned to members belonging to a team.
+The Manage Members menu is used to change the user roles assigned to members belonging to a team.
## User Roles
-The following user roles are assigned from the **Manage Team** menu option in the team site main menu.
+The following user roles are assigned from the **Manage Members** menu option in the team site main menu.
### System Admin
@@ -23,7 +23,7 @@ The Team Administrator is typically a non-technical end user and has the followi
- Access to the "Team Settings" menu from the team site main menu
- Ability to change the team name and import data from Slack export files
-- Access to the "Manage Team" menu and change user roles to the levels of Team Administrator, Member and Inactive
+- Access to the "Manage Members" menu and change user roles to the levels of Team Administrator, Member and Inactive
### Member
diff --git a/doc/help/README.md b/doc/help/README.md
index d07424c70..9271d64dd 100644
--- a/doc/help/README.md
+++ b/doc/help/README.md
@@ -8,5 +8,5 @@ _Note: Help documentation is a work-in-progress. Community contributions highly
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 Teams](Manage-Team.md)
+- [Manage Members](Manage-Members.md)
diff --git a/doc/help/Slack-Import.md b/doc/help/Slack-Import.md
index d8d6170c4..a2914570b 100644
--- a/doc/help/Slack-Import.md
+++ b/doc/help/Slack-Import.md
@@ -1,18 +1,22 @@
-#### Slack Import (Alpha)
+### Slack Import (Beta)
*Note: As a SaaS service, Slack is able to change its export format quickly. If you encounter issues not mentioned in the documentation below, please let us know by [filing an issue](https://github.com/mattermost/platform/issues).*
-The Slack Import feature in Mattermost is in "Preview" and focus is on supporting migration of teams of less than 100 registered users. The feature can be accessed from by Team Administrators and Team Owners via the `Team Settings -> Import` menu option.
+#### Usage
+
+The Slack Import feature in Mattermost is in "Beta" and focus is on supporting migration of teams of less than 100 registered users. The feature can be accessed from by Team Administrators and Team Owners via the `Team Settings -> Import` menu option.
+
+- **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 to install Mattermost in preview mode in less than 5 minutes](../install/Docker-Single-Container.md).
Mattermost currently supports the processing of an "Export" file from Slack containing account information and public channel archives from a Slack team.
-- In the feature preview, emails and usernames from Slack are used to create new Mattermost accounts, connected to messages history in imported Slack channels. Users can activate these accounts and by going to the Password Reset screen in Mattermost to set new credentials.
-- Once logged in, users will have access to previous Slack messages shared in public channels, now imported to Mattermost.
+- Emails and usernames from Slack are used to create new Mattermost accounts, connected to messages history in imported Slack channels. Users can activate these accounts and by going to the Password Reset screen in Mattermost to set new credentials.
+- Once logged in, users will have access to previous Slack messages shared in public channels, now imported to Mattermost.
-Limitations:
+#### Limitations:
- 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.
-- The Preview release of Slack Import does not offer pre-checks or roll-back and will not import Slack accounts with username or email address collisions with existing Mattermost accounts. Also, Slack channel names with underscores will not import. Also, mentions do not yet resolve as Mattermost usernames (still show Slack ID).
+- The Beta release of Slack Import does not offer pre-checks or roll-back and will not import Slack accounts with username or email address collisions with existing Mattermost accounts. Also, Slack channel names with underscores will not import. Also, mentions do not yet resolve as Mattermost usernames (still shows Slack ID).
diff --git a/doc/install/Configuration-Settings.md b/doc/install/Configuration-Settings.md
new file mode 100644
index 000000000..a92893753
--- /dev/null
+++ b/doc/install/Configuration-Settings.md
@@ -0,0 +1,302 @@
+## System Console Settings
+
+The System Console user interface lets system administrators manage a Mattermost server and multiple teams from a web-based user interface. The first user added to a new Mattermost install is assigned the system administrator role and can access the System Console from the main menu of any team. Setting changes in the System Console are stored in `config.json`.
+
+### Service Settings
+
+General settings to configure the listening address, login security, testing, webhooks and service integration of Mattermost.
+
+#### System
+
+```"ListenAddress": ":8065"```
+The IP address on which to listen and the port on which to bind. Entering ":8065" will bind to all interfaces or you can choose one like "127.0.0.1:8065". Changing this will require a server restart before taking effect.
+
+```"MaximumLoginAttempts": 10```
+Failed login attempts allowed before a user is locked out and required to reset their password via email.
+
+```"SegmentDeveloperKey": ""```
+For users running SaaS services, signup for a key at Segment.com to track metrics.
+
+```"GoogleDeveloperKey": ""```
+Set this key to enable embedding of YouTube video previews based on hyperlinks appearing in messages or comments. Instructions to obtain a key available at https://www.youtube.com/watch?v=Im69kzhpR3I. Leaving the field blank disables the automatic generation of YouTube video previews from links.
+
+```"EnableTesting": false```
+"true": `/loadtest` slash command is enabled to load test accounts and test data.
+
+```"EnableSecurityFixAlert": true```
+”true”: System Administrators are notified by email if a relevant security fix alert has been announced in the last 12 hours. Requires email to be enabled.
+
+#### 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.
+
+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.
+
+```"EnablePostUsernameOverride": false```
+"true": Webhooks will be allowed to change the username they are posting as; “false”: Webhooks can only post as the username they were set up with. See http://mattermost.org/webhooks for more details.
+
+```"EnablePostIconOverride": false```
+"true": Webhooks will be allowed to change the icon they post with; “false”: Webhooks can only post with the profile picture of the account they were set up with. See http://mattermost.org/webhooks for more details.
+
+### Team Settings
+
+Settings to configure the appearance, size, and access options for teams.
+
+```"SiteName": "Mattermost"```
+Name of service shown in login screens and UI.
+
+```"MaxUsersPerTeam": 50```
+Maximum number of users per team, including both active and inactive users.
+
+```"EnableTeamCreation": true```
+"true": Ability to create a new team is enabled for all users; “false”: the ability to create teams is disabled. The Create A New Team button is hidden in the main menu UI.
+
+```"EnableUserCreation": true```
+"true": Ability to create new accounts is enabled via inviting new members or sharing the team invite link; “false”: the ability to create accounts is disabled. The create account button displays an error when trying to signup via an email invite or team invite link.
+
+```"RestrictCreationToDomains": ""```
+Teams can only be created by a verified email from this list of comma-separated domains (e.g. "corp.mattermost.com, mattermost.org").
+
+
+### SQL Settings
+
+Settings to configure the data sources, connections, and encryption of SQL databases. Changing properties in this section will require a server restart before taking effect.
+
+```"DriverName": "mysql"```
+"mysql": enables driver to MySQL database; "postgres": enables driver to PostgreSQL database. This setting can only be changed from config.json file, it cannot be changed from the System Console user interface.
+
+```"DataSource": "mmuser:mostest@tcp(dockerhost:3306)/mattermost_test?charset=utf8mb4,utf8"```
+This is the connection string to the master database. When **DriverName**="postgres" then use a connection string in the form “postgres://mmuser:password@localhost:5432/mattermost_test?sslmode=disable&connect_timeout=10”. This setting can only be changed from config.json file, it cannot be changed from the System Console user interface.
+
+```"DataSourceReplicas": []```
+This is a list of connection strings pointing to read replicas of MySQL or PostgreSQL database. If running a single server, set to DataSource. This setting can only be changed from config.json file, it cannot be changed from the System Console user interface.
+
+```"MaxIdleConns": 10```
+Maximum number of idle connections held open to the database.
+
+```"MaxOpenConns": 10```
+Maximum number of open connections held open to the database.
+
+```"Trace": false```
+"true": Executing SQL statements are written to the log for development.
+
+```"AtRestEncryptKey": "7rAh6iwQCkV4cA1Gsg3fgGOXJAQ43QVg"```
+32-character (to be randomly generated via Admin Console) salt available to encrypt and decrypt sensitive fields in database.
+
+
+### Email Settings
+
+Settings to configure email signup, notifications, security, and SMTP options.
+
+#### Signup
+
+```"EnableSignUpWithEmail": true```
+"true": Allow team creation and account signup using email and password; “false”: Email signup is disabled and users are not able to invite new members. This limits signup to single-sign-on services like OAuth or LDAP.
+
+#### Notifications
+
+```"SendEmailNotifications": false```
+"true": Enables sending of email notifications. “false”: Disables email notifications for developers who may want to skip email setup for faster development.
+
+```"RequireEmailVerification": false```
+"true": Require email verification after account creation prior to allowing login; “false”: Users do not need to verify their email address prior to login. Developers may set this field to false so skip sending verification emails for faster development.
+
+```"FeedbackName": ""```
+Name displayed on email account used when sending notification emails from Mattermost system.
+
+```"FeedbackEmail": ""```
+Address displayed on email account used when sending notification emails from Mattermost system.
+
+#### SMTP
+
+```"SMTPUsername": ""```
+Obtain this credential from the administrator setting up your email server.
+
+```"SMTPPassword": ""```
+Obtain this credential from the administrator setting up your email server.
+
+```"SMTPServer": ""```
+Location of SMTP email server.
+
+```"SMTPPort": ""```
+Port of SMTP email server.
+
+#### Security
+
+```"ConnectionSecurity": ""```
+"none": Send email over an unsecure connection; "TLS": Communication between Mattermost and your email server is encrypted; “STARTTLS”: Attempts to upgrade an existing insecure connection to a secure connection using TLS.
+
+```"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.
+
+
+### File Settings
+
+Settings to configure storage, appearance, and security of files and images.
+
+#### File Storage
+
+```"DriverName": "local"```
+System used for file storage. “local”: Files and images are stored on the local file system. “amazons3”: Files and images are stored on Amazon S3 based on the provided access key, bucket and region fields.
+
+```"Directory": "./data/"```
+Directory to which files are written. If blank, directory will be set to ./data/.
+
+```"AmazonS3AccessKeyId": ""```
+Obtain this credential from your Amazon EC2 administrator.
+
+```"AmazonS3SecretAccessKey": ""```
+Obtain this credential from your Amazon EC2 administrator.
+
+```"AmazonS3Bucket": ""```
+Name you selected for your S3 bucket in AWS.
+
+```"AmazonS3Region": ""```
+AWS region you selected for creating your S3 bucket. Refer to [AWS Reference Documentation](http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region) and choose this variable from the Region column.
+
+#### Image Settings
+
+```"ThumbnailWidth": 120```
+Width of thumbnails generated from uploaded images. Updating this value changes how thumbnail images render in future, but does not change images created in the past.
+
+```"ThumbnailHeight": 100```
+Height of thumbnails generated from uploaded images. Updating this value changes how thumbnail images render in future, but does not change images created in the past.
+
+```"PreviewWidth": 1024```
+Maximum width of preview image. Updating this value changes how preview images render in future, but does not change images created in the past.
+
+```"PreviewHeight": 0```
+Maximum height of preview image ("0": Sets to auto-size). Updating this value changes how preview images render in future, but does not change images created in the past.
+
+```"ProfileWidth": 128```
+The width to which profile pictures are resized after being uploaded via Account Settings.
+
+```"ProfileHeight": 128```
+The height to which profile pictures are resized after being uploaded via Account Settings.
+
+```"EnablePublicLink": true```
+”true”: Allow users to share public links to files and images when previewing; “false”: The Get Public Link option is hidden from the image preview user interface.
+
+```"PublicLinkSalt": "A705AklYF8MFDOfcwh3I488G8vtLlVip"```
+32-character (to be randomly generated via Admin Console) salt added to signing of public image links.
+
+
+### Log Settings
+
+Settings to configure the console and log file output, detail level, format and location of error messages.
+
+#### Console Settings
+
+```"EnableConsole": true```
+“true”: Output log messages to the console based on **ConsoleLevel** option. The server writes messages to the standard output stream (stdout).
+
+```"ConsoleLevel": "DEBUG"```
+Level of detail at which log events are written to the console when **EnableConsole**=true. ”ERROR”: Outputs only error messages; “INFO”: Outputs error messages and information around startup and initialization; “DEBUG”: Prints high detail for developers debugging issues.
+
+#### Log File Settings
+
+```"EnableFile": true```
+”true”: Log files are written to files specified in **FileLocation**.
+
+```"FileLevel": "INFO"```
+Level of detail at which log events are written to log files when **EnableFile**=true. “ERROR”: Outputs only error messages; “INFO”: Outputs error messages and information around startup and initialization; “DEBUG”: Prints high detail for developers debugging issues.
+
+```"FileFormat": ""```
+Format of log message output. If blank, **FileFormat** = "[%D %T] [%L] (%S) %M", where:
+
+ %T Time (15:04:05 MST)
+ %t Time (15:04)
+ %D Date (2006/01/02)
+ %d Date (01/02/06)
+ %L Level (FNST, FINE, DEBG, TRAC, WARN, EROR, CRIT)
+ %S Source
+ %M Message
+
+```"FileLocation": ""```
+Directory to which log files are written. If blank, log files write to ./logs/mattermost/mattermost.log. Log rotation is enabled and every 10,000 lines of log information is written to new files stored in the same directory, for example mattermost.2015-09-23.001, mattermost.2015-09-23.002, and so forth.
+
+### Rate Limit Settings
+
+Settings to enable API rate limiting and configure requests per second, user sessions and variables for rate limiting. Changing properties in this section will require a server restart before taking effect.
+
+```"EnableRateLimiter": true```
+”true”: APIs are throttled at the rate specified by **PerSec**.
+
+```"PerSec": 10```
+Throttle API at this number of requests per second if **EnableRateLimiter**=true.
+
+```"MemoryStoreSize": 10000```
+Maximum number of user sessions connected to the system as determined by **VaryByRemoteAddr** and **VaryByHeader** variables.
+
+```"VaryByRemoteAddr": true```
+"true": Rate limit API access by IP address.
+
+```"VaryByHeader": ""```
+Vary rate limiting by HTTP header field specified (e.g. when configuring Ngnix set to "X-Real-IP", when configuring AmazonELB set to "X-Forwarded-For").
+
+### Privacy Settings
+
+Settings to configure the name and email privacy of users on your system.
+
+```"ShowEmailAddress": true```
+“true”: Show email address of all users; "false": Hide email address of users from other users in the user interface, including team owners and team administrators. This is designed for managing teams where users choose to keep their contact information private.
+
+```"ShowFullName": true```
+”true”: Show full name of all users; “false”: hide full name of users from other users including team owner and team administrators.
+
+### GitLab Settings
+
+Settings to configure account and team creation using GitLab OAuth.
+
+```"Enable": false```
+“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".
+
+```"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".
+
+```"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.
+
+```"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.
+
+```"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.
+
+## Config.json Settings Not in System Console
+
+System Console allows an IT Admin to update settings defined in `config.json`. However there are a number of settings in `config.json` unavailable in the System Console and require update from the file itself. We describe them here:
+
+### Service Settings
+
+```"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"```
+Font used in auto-generated profile pics with colored backgrounds.
+
+### GitLab Settings
+
+```"Scope": ""```
+Standard setting for OAuth to determine the scope of information shared with OAuth client. Not currently supported by GitLab OAuth.
diff --git a/doc/install/Release-Numbering.md b/doc/install/Release-Numbering.md
index 71374f7ef..3b0391cff 100644
--- a/doc/install/Release-Numbering.md
+++ b/doc/install/Release-Numbering.md
@@ -14,4 +14,4 @@ Major Build Number:
Minor Build Number:
-- Indicates bugfix/security releases (e.g. 1.2.5, 1.2.6)
+- Indicates a bug fix or security release (e.g. 1.2.5, 1.2.6)
diff --git a/doc/install/SMTP-Email-Setup.md b/doc/install/SMTP-Email-Setup.md
index 86e2bb20e..fcf012804 100644
--- a/doc/install/SMTP-Email-Setup.md
+++ b/doc/install/SMTP-Email-Setup.md
@@ -39,3 +39,17 @@ To enable email, turn this option off by setting `ByPassEmail=false` and configu
2. Kill the process `kill pid`
3. The service should restart automatically. Verify the Mattermost service is running with `ps -A`
4. Current logged in users will not be affected, but upon logging out or session expiration users will be required to verify their email address.
+
+### Troubleshooting SMTP
+
+If you have issues with your SMTP install, from your Mattermost team site go to the main menu and open `System Console > Logs` to look for error messages related to your setup. You can do a search for the error code to narrow down the issue. Sometimes ISPs require nuanced setups for SMTP and error codes can hint at how to make the proper adjustments.
+
+For example, if `System Console > Logs` has an error code reading:
+
+```
+Connection unsuccessful: Failed to add to email address - 554 5.7.1 <unknown[IP-ADDRESS]>: Client host rejected: Access denied
+```
+
+Search for `554 5.7.1 error` and `Client host rejected: Access denied`.
+
+
diff --git a/doc/install/Troubleshooting.md b/doc/install/Troubleshooting.md
new file mode 100644
index 000000000..8d82100d8
--- /dev/null
+++ b/doc/install/Troubleshooting.md
@@ -0,0 +1,7 @@
+### Mattermost Troubleshooting
+
+#### Important notes
+
+1. **DO NOT manipulate the Mattermost database**
+ - In particular, DO NOT delete data from the database, as this will most likely crash Mattermost in strange ways. Mattermost is designed to archive content continously and generally assumes data is never deleted.
+
diff --git a/doc/integrations/Single-Sign-On/Gitlab.md b/doc/integrations/Single-Sign-On/Gitlab.md
index 87889df66..e503a158b 100644
--- a/doc/integrations/Single-Sign-On/Gitlab.md
+++ b/doc/integrations/Single-Sign-On/Gitlab.md
@@ -12,10 +12,12 @@ The following steps can be used to configure Mattermost to use GitLab as a singl
3. Submit the application and copy the given _Id_ and _Secret_ into the appropriate _SSOSettings_ fields in config/config.json
4. Also in config/config.json, set _Allow_ to `true` for the _gitlab_ section, leave _Scope_ blank and use the following for the endpoints:
- * _AuthEndpoint_: `<your-gitlab-url>/oauth/authorize` (example http://localhost:3000/oauth/authorize)
- * _TokenEndpoint_: `<your-gitlab-url>/oauth/token`
- * _UserApiEndpoint_: `<your-gitlab-url>/api/v3/user`
+ * _AuthEndpoint_: `https://<your-gitlab-url>/oauth/authorize` (example https://example.com/oauth/authorize)
+ * _TokenEndpoint_: `https://<your-gitlab-url>/oauth/token`
+ * _UserApiEndpoint_: `https://<your-gitlab-url>/api/v3/user`
+
+ Note: Make sure your `HTTPS` or `HTTP` prefix for endpoint URLs matches how your server configuration.
-6. (Optional) If you would like to force all users to sign-up with GitLab only, in the _ServiceSettings_ section of config/config.json please set _DisableEmailSignUp_ to `true`.
+5. (Optional) If you would like to force all users to sign-up with GitLab only, in the _ServiceSettings_ section of config/config.json please set _DisableEmailSignUp_ to `true`.
-7. Restart your Mattermost server to see the changes take effect.
+6. Restart your Mattermost server to see the changes take effect.
diff --git a/doc/integrations/webhooks/Incoming-Webhooks.md b/doc/integrations/webhooks/Incoming-Webhooks.md
index 645d4861e..c6323a24a 100644
--- a/doc/integrations/webhooks/Incoming-Webhooks.md
+++ b/doc/integrations/webhooks/Incoming-Webhooks.md
@@ -1,19 +1,19 @@
# Incoming Webhooks
-Incoming webhooks allow external applications, written in the programming language of your choice--to post messages into Mattermost channels and private groups by sending a specifically formatted JSON payload via HTTP POST request to a secret Mattermost URL generated specifically for each application.
+Incoming webhooks allow external applications, written in the programming language of your choice--to post messages into Mattermost channels and private groups by sending a specifically formatted JSON payload via HTTP POST request to a secret Mattermost URL generated specifically for each application.
-A couple key points:
+A couple key points:
-- **Mattermost incoming webhooks are Slack-compatible.** If you've used Slack's incoming webhooks to create integrations, you can copy and paste that code to create Mattermost integrations. Mattermost automatically translates Slack's propretiary JSON payload format into markdown to render in Mattermost messages.
+- **Mattermost incoming webhooks are Slack-compatible.** If you've used Slack's incoming webhooks to create integrations, you can copy and paste that code to create Mattermost integrations. Mattermost automatically translates Slack's propretiary JSON payload format into markdown to render in Mattermost messages.
- **Mattermost incoming webhooks support full markdown.** A rich range of formatting unavailable in Slack is made possible through [markdown support](../../usage/Markdown.md) in Mattermost, incuding headings, formatted fonts, tables, inline images and other options supported by [Mattermost Markdown].
_Example:_
-Suppose you wanted to create a notification of the status of a daily build, with a table of total tests run and total tests failed by component category, with links to failed tests by category. You could create the following JSON payload to post to a Mattermost channel using webhooks:
+Suppose you wanted to create a notification of the status of a daily build, with a table of total tests run and total tests failed by component category, with links to failed tests by category. You could create the following JSON payload to post to a Mattermost channel using webhooks:
```
payload={"text": "
-***
+***
##### Build Break - Project X - December 12, 2015 - 15:32 GMT +0
| Component | Tests Run | Tests Failed |
|:-----------|:------------|:-----------------------------------------------|
@@ -25,56 +25,68 @@ payload={"text": "
```
Which would render in a Mattermost message as follows:
-***
+***
##### Build Break - Project X - December 12, 2015 - 15:32 GMT +0
| Component | Tests Run | Tests Failed |
|:------------ |:---------------|:-----|
| Server | 948 | :white_check_mark: 0 |
| Web Client | 123 | :warning: [2 (see details)](http://linktologs) |
| iOS Client | 78 | :warning: [3 (see details)](http://linktologs) |
-***
+***
+
+### Enabling Incoming Webhooks
+Incoming webhooks should be enabled on your Mattermost instance by default, but if they are not you'll need to get your system administrator to enable them. If you are the system administrator you can enable them by doing the following:
+
+1. Login to your Mattermost team account that has the system administrator role.
+1. Enable incoming webhooks from **System Console -> Service Settings**.
+1. (Optional) Configure the **Enable Overriding of Usernames from Webhooks** option to allow external applications to post messages under any name. If not enabled, the username of the creator of the webhook URL is used to post messages.
+2. (Optional) Configure the **Enable Overriding of Icon from Webhooks** option to allow external applciations to change the icon of the account posting messages. If not enabled, the icon of the creator of the webhook URL is used to post messages.
+
+### Setting Up Existing Integrations
+If you've already found or built an integration and are just looking to hook it up, then you should just need to follow the specific instructions of that integration. If the integration is using Mattermost incoming webhooks, then at some point in the instructions it will ask for a webhook URL. You can get this URL by following the first step in the next section _Creating Integrations using Incoming Webhooks_.
### Creating Integrations using Incoming Webhooks
-You can create a webhook integration to post into Mattermost channels and private groups using these steps:
+You can create a webhook integration to post into Mattermost channels and private groups using these steps:
-1. Enable incoming webhooks from **System Console -> Service Settings**
+**Note: Incoming webhooks must be enabled. Only your Mattermost system administrator can enable incoming webhooks if they are currently disabled.**
- 1. Optionally configure the **Enable Overriding of Usernames from Webhooks** option to allow external applications to post messages under any name. If not enabled, the username of the creator of the webhook URL is used to post messages.
- 2. Optionally configure the **Enable Overriding of Icon from Webhooks** option to allow external applciations to change the icon of the account posting messages. If not enabled, the icon of the creator of the webhook URL is used to post messages.
-
2. Create a Mattermost Incoming Webhook URL
1. Login to your Mattermost team site and go to **Account Settings -> Integrations**
2. Next to **Incoming Webhooks** click **Edit**
3. Select the channel or private group to receive webhook payloads, then click **Add** to create the webhook
-
-3. Write a function to call the URL with a properly formatted JSON payload
- 1. To make sure everything works, try a curl command from your terminal or command line to send a JSON string as the `payload` parameter in a HTTP POST request.
- - _Example:_
+ 4. To see your new webhook in action, try a curl command from your terminal or command-line to send a JSON string as the `payload` parameter in a HTTP POST request.
+ 1. Example:
```
curl -i -X POST -d 'payload={"text": "Hello, this is some text."}' http://yourmattermost.com/hooks/xxx-generatedkey-xxx
-```
- 2. In addition, with **Enable Overriding of Usernames from Webhooks** turned on, you can also override the username the message posts as by providing a `username` parameter in your JSON payload. For example, you might want your message looking like it came from a robot so you can use ```payload={"username": "robot", "text": "Hello, this is some text."}``` to change the username of the post to robot. Note, to combat any malicious users from trying to use this to perform [phishing attacks](https://en.wikipedia.org/wiki/Phishing) a `BOT` indicator appears next to posts coming from incoming webhooks.
- 3. With **Enable Overriding of Icon from Webhooks** turned on, you can similarly change the icon the message posts with by providing a link to an image in the `icon_url` parameter of your payload. For example, ```payload={"icon_url": "http://somewebsite.com/somecoolimage.jpg", "text": "Hello, this is some text."}``` will post using whatever image is located at `http://somewebsite.com/somecoolimage.jpg` as the icon for the post.
+```
- 2. Set up your integration running on your own machine or a hosting service like AWS or Heroku, to start sending real time updates to Mattermost channels and private groups.
+3. Build your integration in the programming language of your choice
+ 1. Most integrations will be used to translate some sort of output from another system to an appropriately formatted input that will be passed into the Mattermost webhook URL. For example, an integration could take events generated by [GitLab outgoing webhooks](http://doc.gitlab.com/ee/web_hooks/web_hooks.html) and parse them into a JSON body to post into Mattermost.
+ 1. To get the message posted into Mattermost, your integration will need to create an HTTP POST request that will submit to the incoming webhook URL you created before. The body of the request must have a `payload` that contains a JSON object that specifies a `text` parameter. For example, `payload={"text": "Hello, this is some text."}` is a valid body for a request.
+ 2. Setup your integration running on Heroku, an AWS server or a server of your own to start sending real time updates to Mattermost channels and private groups.
Additional Notes:
-1. For the JSON payload, if `Content-Type` is specified as `application/json` in the headers of the HTTP request then the body of the request can be direct JSON. ```{"text": "Hello, this is some text."}```
+1. For the HTTP request body, if `Content-Type` is specified as `application/json` in the headers of the HTTP request then the body of the request can be direct JSON. For example, ```{"text": "Hello, this is some text."}```
+
+2. You can override the channel specified in the webhook definition by specifying a `channel` parameter in your payload. For example, you might have a single webhook created for _Town Square_, but you can use ```payload={"channel": "off-topic", "text": "Hello, this is some text."}``` to send a message to the _Off-Topic_ channel using the same webhook URL.
-2. You can override the channel specified in the webhook definition by specifying a `channel` parameter in your payload. For example, you might have a single webhook created for _Town Square_, but you can use ```payload={"channel": "off-topic", "text": "Hello, this is some text."}``` to send a message to the _Off-Topic_ channel using the same webhook URL.
+1. In addition, with **Enable Overriding of Usernames from Webhooks** turned on, you can also override the username the message posts as by providing a `username` parameter in your JSON payload. For example, you might want your message looking like it came from a robot so you can use ```payload={"username": "robot", "text": "Hello, this is some text."}``` to change the username of the post to robot. Note, to combat any malicious users from trying to use this to perform [phishing attacks](https://en.wikipedia.org/wiki/Phishing) a `BOT` indicator appears next to posts coming from incoming webhooks.
-3. Also, as mentioned previously, [markdown](../../usage/Markdown.md) can be used to create richly formatted payloads, for example: ```payload={"text": "# A Header\nThe _text_ below **the** header."}``` creates a messages with a header, a carriage return and bold text for "the".
+2. With **Enable Overriding of Icon from Webhooks** turned on, you can similarly change the icon the message posts with by providing a link to an image in the `icon_url` parameter of your payload. For example, ```payload={"icon_url": "http://somewebsite.com/somecoolimage.jpg", "text": "Hello, this is some text."}``` will post using whatever image is located at `http://somewebsite.com/somecoolimage.jpg` as the icon for the post.
+
+3. Also, as mentioned previously, [markdown](../../usage/Markdown.md) can be used to create richly formatted payloads, for example: ```payload={"text": "# A Header\nThe _text_ below **the** header."}``` creates a messages with a header, a carriage return and bold text for "the".
4. Just like regular posts, the text will be limited to 4000 characters at maximum.
-### Slack Compatibility
+### 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:
+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:
-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.
+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.
-To learn more about Incoming Webhooks and to see samples and community contributions, please visit <http://mattermost.org/webhooks>
+To see samples and community contributions, please visit <http://mattermost.org/webhooks>.
+
generated by cgit v1.2.3-1-g7c22 (git 2.25.1) at 2024-08-26 19:36:19 +0000