diff options
Diffstat (limited to 'doc/install')
| -rw-r--r-- | doc/install/Administration.md | 114 | ||||
| -rw-r--r-- | doc/install/Amazon-Elastic-Beanstalk.md | 28 | ||||
| -rw-r--r-- | doc/install/Command-Line-Tools.md | 81 | ||||
| -rw-r--r-- | doc/install/Configuration-Settings.md | 409 | ||||
| -rw-r--r-- | doc/install/Docker-Single-Container.md | 124 | ||||
| -rw-r--r-- | doc/install/LDAP-Setup.md | 34 | ||||
| -rw-r--r-- | doc/install/Production-Debian.md | 332 | ||||
| -rw-r--r-- | doc/install/Production-RHEL6.md | 231 | ||||
| -rw-r--r-- | doc/install/Production-RHEL7.md | 238 | ||||
| -rw-r--r-- | doc/install/Production-Ubuntu.md | 215 | ||||
| -rw-r--r-- | doc/install/Release-Numbering.md | 23 | ||||
| -rw-r--r-- | doc/install/Requirements.md | 91 | ||||
| -rw-r--r-- | doc/install/SMTP-Email-Setup.md | 107 | ||||
| -rw-r--r-- | doc/install/Troubleshooting.md | 66 | ||||
| -rw-r--r-- | doc/install/Upgrade-Guide.md | 81 |
15 files changed, 0 insertions, 2174 deletions
diff --git a/doc/install/Administration.md b/doc/install/Administration.md deleted file mode 100644 index 53f413d04..000000000 --- a/doc/install/Administration.md +++ /dev/null @@ -1,114 +0,0 @@ -# Administration - -This document provides instructions for common administrator tasks - -#### Important notes - -##### **DO NOT manipulate the Mattermost database** - - In particular, DO NOT delete data from the database, as Mattermost is designed to stop working if data integrity has been compromised. The system is designed to archive content continously and generally assumes data is never deleted. - -### Common Tasks - -##### Creating System Administrator account from commandline - - 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. - -##### Deactivating a user - - - 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/Amazon-Elastic-Beanstalk.md b/doc/install/Amazon-Elastic-Beanstalk.md deleted file mode 100644 index 56650fc93..000000000 --- a/doc/install/Amazon-Elastic-Beanstalk.md +++ /dev/null @@ -1,28 +0,0 @@ - -## AWS Elastic Beanstalk Setup (Docker) -These instructions will guide you through the process of setting up Mattermost for product evaluation using an EBS Docker single-container application using [Dockerrun.aws.zip][Dockerrun.aws]. - -1. From your [AWS console]( https://console.aws.amazon.com/console/home) select **Elastic Beanstalk** under the Compute section. -2. Select **Create New Application** from the top right. -3. Name your Elastic Beanstalk application and click **Next**, -4. Select **Create web server** on the New Enviroment page. -5. If asked, select **Create an IAM role and instance profile**, then click **Next**. -6. On the Enviroment Type page, - 1. Set Predefined Configuration to **Docker** under the generic heading in the drop-down list. - 2. Set Environment Type to **Single instance** in the drop-down list. - 3. Click **Next**. -7. For Application Source, select **Upload your own** and upload the [Dockerrun.aws.zip][Dockerrun.aws] file, then click **Next**. -8. Type an Environment Name and URL. Make sure the URL is available by clicking **Check availability**, then click **Next**. -9. The options on the Additional Resources page may be left at default unless you wish to change them. Click **Next**. -10. On the Configuration Details page, - 1. Select an Instance Type of **t2.small** or larger. - 2. The remaining options may be left at their default values unless you wish to change them. Click **Next**. -11. Environment tags may be left blank. Click **Next**. -12. You will be asked to review your information, then click **Launch**. -14. It may take a few minutes for beanstalk to launch your environment. If the launch is successful, you will see a see a large green checkmark and the Health status should change to “Green”. -15. Test your environment by clicking the domain link next to your application name at the top of the dashboard. Alternatively, enter the domain into your browser in the form `http://<your-ebs-application-url>.elasticbeanstalk.com`. You can also map your own domain if you wish. If everything is working correctly, the domain should navigate you to the Mattermost signup page. Enjoy exploring Mattermost! - -### (Recommended) Enable Email -The default single-container Docker instance for Mattermost is designed for product evaluation, and sets `SendEmailNotifications=false` so the product can function without enabling email. To see the product's full functionality, [enabling SMTP email is recommended](SMTP-Email-Setup.md). - -[Dockerrun.aws]: https://github.com/mattermost/platform/raw/master/docker/1.4/Dockerrun.aws.zip diff --git a/doc/install/Command-Line-Tools.md b/doc/install/Command-Line-Tools.md deleted file mode 100644 index ff6f110fd..000000000 --- a/doc/install/Command-Line-Tools.md +++ /dev/null @@ -1,81 +0,0 @@ -# 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 deleted file mode 100644 index 7ee440b7c..000000000 --- a/doc/install/Configuration-Settings.md +++ /dev/null @@ -1,409 +0,0 @@ -## 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. - -```"EnableDeveloper": false``` -"true": Users are alerted to any console errors that occur. - -```"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. - -```"SessionLengthWebInDays" : 30``` -Set the number of days before web sessions expire and users will need to log in again. - -```"SessionLengthMobileInDays" : 30``` -Set the number of days before native mobile sessions expire. - -```"SessionLengthSSOInDays" : 30``` -Set the number of days before SSO sessions expire. - -```"SessionCacheInMinutes" : 10``` -Set the number of minutes to cache a session in memory. - -```"WebsocketSecurePort": 443``` -The port to use for secure websocket connections being initiated from the client. By default wss:// uses port 443. Some server configurations (e.g. Cloudfoundry) support wss on a different port. - -```"WebsocketPort": 80``` -The port to use for websocket connections being initiated from the client. By default ws:// uses port 80. - - -#### 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 > 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. - -```"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 and user accounts 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 - -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. Setting this to true removes the **Preview Mode: Email notifications have not been configured** banner (requires logging out and logging back in after setting is changed) - - -```"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. - -#### 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 - -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. - -### Support Settings - -```"TermsOfServiceLink": "/static/help/terms.html"``` -Set the link for the terms of service. - -```"PrivacyPolicyLink": "/static/help/privacy.html"``` -Set the link for the privacy policy. - -```"AboutLink": "/static/help/about.html"``` -Set the link for the about page. - -```"HelpLink": "/static/help/help.html"``` -Set the link for the help page. - -```"ReportAProblemLink": "/static/help/report_problem.html"``` -Set the link for the support website. - -`"SupportEmail":"feedback@mattermost.com"` -Set an email for feedback or support requests. - -### LDAP Settings (Enterprise) - -Settings used to enable and configure LDAP authentication with Mattermost. Available in the Enterprise version of Mattermost. - -```"Enable Login With LDAP": "false"``` -"true": Mattermost allows login using LDAP. - -```"LDAP Server": ""``` -The domain or IP address of the LDAP server. - -```"LDAP Port": "389"``` -The port Mattermost will use to connect to the LDAP server. Default is 389. - -```"BaseDN": ""``` -The Base DN is the Distinguished Name of the location where Mattermost should start its search for users in the LDAP tree. - -```"Bind Username": ""``` -The username used to perform the LDAP search. This should typically be an account created specifically for use with Mattermost. It should be a read only account with access limited to the portion of the LDAP tree specified in the BaseDN field. - -```"Bind Password": ""``` -Password of the user given in “Bind Username”. - -```"First Name Attribute": ""``` -The attribute in the LDAP server that will be used to populate the first name of users in Mattermost. - -```"Last Name Attribute": ""``` -The attribute in the LDAP server that will be used to populate the last name of users in Mattermost. - -```"Email Attribute": ""``` -The attribute in the LDAP server that will be used to populate the email addresses of users in Mattermost. - -```"Username Attribute": ""``` -The attribute in the LDAP server that will be used to populate the username field in Mattermost. This may be the same as the ID Attribute. - -```"ID Attribute": ""``` -The attribute in the LDAP server that will be used as a unique identifier in Mattermost. - -This is the attribute that will be used to create Mattermost accounts. It should be an LDAP attribute with a value that does not change, such as username or uid. If a user’s Id Attribute changes, it will create a new Mattermost account unassociated with their old one. - -This is also the value used to log in to Mattermost in the “LDAP Username” field on the sign in page. Normally this attribute is the same as the “Username Attribute” field above. If your team typically uses domain\username to sign in to other services with LDAP, you may choose to put domain\username in this field to maintain consistency between sites. - -```"Query Timeout (seconds)": "60"``` -The timeout value for queries to the LDAP server. Increase this value if you are getting timeout errors caused by a slow LDAP server. - -## 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. - -### File Settings - -```"InitialFont": "luximbi.ttf"``` -Font used in auto-generated profile pics with colored backgrounds. - -```"AmazonS3Endpoint": ""``` -Set an endpoint URL for an Amazon S3 instance. - -```"AmazonS3BucketEndpoint": ""``` -Set an endpoint URL for Amazon S3 buckets. - -```"AmazonS3LocationConstraint": false``` -Set whether the S3 region is location constrained. - -```Added: "AmazonS3LowercaseBucket": false``` -Set whether bucket names are fully lowercase or not. - -### 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/Docker-Single-Container.md b/doc/install/Docker-Single-Container.md deleted file mode 100644 index 7c0784ad0..000000000 --- a/doc/install/Docker-Single-Container.md +++ /dev/null @@ -1,124 +0,0 @@ -# Local Machine Setup and Upgrade - -The following install instructions are for single-container installs of Mattermost using Docker for exploring product functionality and upgrading to newer versions. - -### One-line Docker Install ### - -If you have Docker set up, Mattermost installs in one-line: -`docker run --name mattermost-dev -d --publish 8065:80 mattermost/platform` - -Otherwise, see step-by-step available: - -### Mac OSX ### - -1. Install Docker Toolbox using instructions at: http://docs.docker.com/installation/mac/ - 1. Start Docker Toolbox from the command line and run: `docker-machine create -d virtualbox dev` -2. Get your Docker IP address with: `docker-machine ip dev` -3. Use `sudo nano /etc/hosts` to add `<Docker IP> dockerhost` to your /etc/hosts file -4. Run: `docker-machine env dev` and copy the export statements to your ~/.bash\_profile by running `sudo nano ~/.bash_profile`. Then run: `source ~/.bash_profile` -5. Run: `docker run --name mattermost-dev -d --publish 8065:80 mattermost/platform` -6. When docker is done fetching the image, open http://dockerhost:8065/ in your browser. - -### Ubuntu ### -1. Follow the instructions at https://docs.docker.com/installation/ubuntulinux/ or use the summary below: - - ``` bash - sudo apt-get update - sudo apt-get install wget - wget -qO- https://get.docker.com/ | sh - sudo usermod -aG docker <username> - sudo service docker start - newgrp docker - ``` - -2. Start docker container: - - ``` bash - docker run --name mattermost-dev -d --publish 8065:80 mattermost/platform - ``` - -3. When docker is done fetching the image, open http://localhost:8065/ in your browser. - -### Arch ### -1. Install Docker using the following commands: - - ``` bash - pacman -S docker - systemctl enable docker.service - systemctl start docker.service - gpasswd -a <username> docker - newgrp docker - ``` - -2. Start Docker container: - - ``` bash - docker run --name mattermost-dev -d --publish 8065:80 mattermost/platform - ``` - -3. When Docker is done fetching the image, open http://localhost:8065/ in your browser. - -### Additional Notes ### -- If you want to work with the latest master from the repository (i.e. not a stable release) you can run the cmd: - - ``` bash - docker run --name mattermost-dev -d --publish 8065:80 mattermost/platform:dev - ``` - -- Instructions on how to update your Docker image are found below. - -- If you wish to remove mattermost-dev use: - - ``` bash - docker stop mattermost-dev - docker rm -v mattermost-dev - ``` - -- If you wish to gain access to a shell on the container use: - - ``` bash - docker exec -ti mattermost-dev /bin/bash - ``` - -## Configuration Settings - -There are a few configuration settings you might want to adjust when setting up your instance of Mattermost. You can edit them in `config.json` or `config_docker.json` if you're running a Docker instance. - -* *EmailSettings*:*ByPassEmail* - If this is set to true, then users on the system will not need to verify their email addresses when signing up. In addition, no emails will ever be sent. -* *ServiceSettings*:*UseLocalStorage* - If this is set to true, then your Mattermost server will store uploaded files in the storage directory specified by *StorageDirectory*. *StorageDirectory* must be set if *UseLocalStorage* is set to true. -* *ServiceSettings*:*StorageDirectory* - The file path where files will be stored locally if *UseLocalStorage* is set to true. The operating system user that is running the Mattermost application must have read and write privileges to this directory. -* *AWSSettings*:*S3*\* - If *UseLocalStorage* is set to false, and the S3 settings are configured here, then Mattermost will store files in the provided S3 bucket. - -### (Recommended) Enable Email - -The default single-container Docker instance for Mattermost is designed for product evaluation, and sets `ByPassEmail=true` so the product can run without enabling email, when doing so maybe difficult. - -To see the product's full functionality, [enabling SMTP email is recommended](SMTP-Email-Setup.md). - -## Upgrading Mattermost - -### Docker ### -To upgrade your Docker image to a preview of the latest stable release (NOTE: this will erase all data in the Docker container, including the database): - -1. Stop your Docker container by running: - - ``` bash - docker stop mattermost-dev - ``` -2. Delete your Docker container by running: - - ``` bash - docker rm mattermost-dev - ``` -3. Update your Docker image by running: - - ``` bash - docker pull mattermost/platform - ``` -4. Start your Docker container by running: - - ``` bash - docker run --name mattermost-dev -d --publish 8065:80 mattermost/platform - ``` - -To upgrade to the latest development build on master from the repository replace `mattermost/platform` with `mattermost/platform:dev` in the instructions 3) and 4) above. diff --git a/doc/install/LDAP-Setup.md b/doc/install/LDAP-Setup.md deleted file mode 100644 index a619e645e..000000000 --- a/doc/install/LDAP-Setup.md +++ /dev/null @@ -1,34 +0,0 @@ -## LDAP Setup - -LDAP authentication is available in the Enterprise version of Mattermost. -### How to enable LDAP - -After installing Mattermost: - -1. Create a team using email authentication - - Note: The first account used to create a team will be the “System Administrator” account, used to configure settings for your Mattermost site - 3. Go to Main Menu (the three dots near your team name in the top left of your screen) > **System Console** - 4. Go to LDAP Settings - 5. Fill in the fields to set up Mattermost authentication with your LDAP server - - After LDAP has been enabled, users should be able to go to your Mattermost site and sign in using their LDAP credentials. The “LDAP username” will be the attribute set in the “Id Attribute” field. - - **Note: In the initial implementation of LDAP, if a user attribute changes on the LDAP server it will be updated the next time the user enters their credentials to log in to Mattermost. This includes if a user is made inactive or removed from an LDAP server. Synchronization with LDAP servers is planned in a future release.** - -### Switching System Administrator account to LDAP authentication - -If you would like to switch your System Administrator account to LDAP authentication, it is recommended you do the following: - -1. Create a new account using LDAP - - Note: If your LDAP credentials use the same email address as your System Administrator account, it is recommended you change the email on your System Administrator account by going to Main Menu -> Account Settings -> General -> Email. This will free up the email address so it can be used by the LDAP account. - 2. Sign in to your email based System Administrator account - 3. Navigate to the System Console - 4. Go to Teams -> Team Name -> Users, and find your new LDAP user account - 5. Promote your LDAP account to “System Administrator” using the dropdown menu beside the username - 6. Log in with your LDAP account - 7. Navigate to the System Console - 8. Go to Teams -> Team Name -> Users, and find your old email based System Administrator account - 9. Make the email account “Inactive” using the dropdown beside the username - - **Note: If you make the email account inactive without promoting another account to System Administrator, you will lose your System Administrator privileges. This can be fixed by promoting another account to System Administrator using the command line.** - diff --git a/doc/install/Production-Debian.md b/doc/install/Production-Debian.md deleted file mode 100644 index ffe3d79e8..000000000 --- a/doc/install/Production-Debian.md +++ /dev/null @@ -1,332 +0,0 @@ -# (Community Guide) Production Installation on Debian Jessie (x64) - -Note: This install guide has been generously contributed by the Mattermost community. It has not yet been tested by the core team. We have [an open ticket](https://github.com/mattermost/platform/issues/1185) requesting community help testing and improving this guide. Once the community has confirmed we have multiple deployments on these instructions, we can update the text here. If you're installing on Debian anyway, please let us know any issues or instruciton improvements? https://github.com/mattermost/platform/issues/1185 - - -## Install Debian Jessie (x64) -1. Set up 3 machines with Debian Jessie with 2GB of RAM or more. The servers will be used for the Load Balancer, Mattermost (this must be x64 to use pre-built binaries), and Database. -1. This can also be set up all on a single server for small teams: - * I have a Mattermost instance running on a single Debian Jessie server with 1GB of ram and 30 GB SSD - * This has been working in production for ~20 users without issue. - * The only difference in the below instructions for this method is to do everything on the same server -1. Make sure the system is up to date with the most recent security patches. - * ``` sudo apt-get update``` - * ``` sudo apt-get upgrade``` - - -## Set up Database Server -1. For the purposes of this guide we will assume this server has an IP address of 10.10.10.1 -1. Install PostgreSQL 9.3+ (or MySQL 5.6+) - * ``` sudo apt-get install postgresql postgresql-contrib``` -1. PostgreSQL created a user account called `postgres`. You will need to log into that account with: - * ``` sudo -i -u postgres``` -1. You can get a PostgreSQL prompt by typing: - * ``` psql``` -1. Create the Mattermost database by typing: - * ```postgres=# CREATE DATABASE mattermost;``` -1. Create the Mattermost user by typing: - * ```postgres=# CREATE USER mmuser WITH PASSWORD 'mmuser_password';``` -1. Grant the user access to the Mattermost database by typing: - * ```postgres=# GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser;``` -1. You can exit out of PostgreSQL by typing: - * ```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``` -1. Attempt to connect with the new created user to verify everything looks good - * ```psql --host=10.10.10.1 --dbname=mattermost --username=mmuser --password``` - * ```mattermost=> \q``` - - -## 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. Download the latest Mattermost Server by typing: - * ``` wget https://github.com/mattermost/platform/releases/download/v1.3.0/mattermost.tar.gz``` -1. Install Mattermost under /opt - * Unzip the Mattermost Server by typing: - * ``` tar -xvzf mattermost.tar.gz``` - * ``` sudo mv mattermost /opt``` -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 `/opt/mattermost/data`. - * Create the directory by typing: - * ``` sudo mkdir -p /opt/mattermost/data``` -1. Create a system user and group called mattermost that will run this service - * ``` sudo useradd -r mattermost -U``` - * Set the mattermost account as the directory owner by typing: - * ``` sudo chown -R mattermost:mattermost /opt/mattermost``` - * ``` sudo chmod -R g+w /opt/mattermost``` - * Add yourself to the mattermost group to ensure you can edit these files: - * ``` sudo usermod -aG mattermost USERNAME``` -1. Configure Mattermost Server by editing the config.json file at /opt/mattermost/config - * ``` cd /opt/mattermost/config``` - * Edit the file by typing: - * ``` vi config.json``` - * replace `DriverName": "mysql"` with `DriverName": "postgres"` - * replace `"DataSource": "mmuser:mostest@tcp(dockerhost:3306)/mattermost_test?charset=utf8mb4,utf8"` with `"DataSource": "postgres://mmuser:mmuser_password@10.10.10.1:5432/mattermost?sslmode=disable&connect_timeout=10"` - * Optionally you may continue to edit configuration settings in `config.json` or use the System Console described in a later section to finish the configuration. -1. Test the Mattermost Server - * ``` cd /opt/mattermost/bin``` - * Run the Mattermost Server by typing: - * ``` ./platform``` - * You should see a console log like `Server is listening on :8065` letting you know the service is running. - * Stop the server for now by typing `ctrl-c` -1. Setup Mattermost to use the systemd init daemon which handles supervision of the Mattermost process - * ``` sudo touch /etc/init.d/mattermost``` - * ``` sudo vi /etc/init.d/mattermost``` - * Copy the following lines into `/etc/init.d/mattermost` -``` -#! /bin/sh -### BEGIN INIT INFO -# Provides: mattermost -# Required-Start: $network $syslog -# Required-Stop: $network $syslog -# Default-Start: 2 3 4 5 -# Default-Stop: 0 1 6 -# Short-Description: Mattermost Group Chat -# Description: Mattermost: An open-source Slack -### END INIT INFO - -PATH=/sbin:/usr/sbin:/bin:/usr/bin -DESC="Mattermost" -NAME=mattermost -MATTERMOST_ROOT=/opt/mattermost -MATTERMOST_GROUP=mattermost -MATTERMOST_USER=mattermost -DAEMON="$MATTERMOST_ROOT/bin/platform" -PIDFILE=/var/run/$NAME.pid -SCRIPTNAME=/etc/init.d/$NAME - -. /lib/lsb/init-functions - -do_start() { - # Return - # 0 if daemon has been started - # 1 if daemon was already running - # 2 if daemon could not be started - start-stop-daemon --start --quiet \ - --chuid $MATTERMOST_USER:$MATTERMOST_GROUP --chdir $MATTERMOST_ROOT --background \ - --pidfile $PIDFILE --exec $DAEMON --test > /dev/null \ - || return 1 - start-stop-daemon --start --quiet \ - --chuid $MATTERMOST_USER:$MATTERMOST_GROUP --chdir $MATTERMOST_ROOT --background \ - --make-pidfile --pidfile $PIDFILE --exec $DAEMON \ - || return 2 -} - -# -# Function that stops the daemon/service -# -do_stop() { - # Return - # 0 if daemon has been stopped - # 1 if daemon was already stopped - # 2 if daemon could not be stopped - # other if a failure occurred - start-stop-daemon --stop --quiet --retry=TERM/30/KILL/5 \ - --pidfile $PIDFILE --exec $DAEMON - RETVAL="$?" - [ "$RETVAL" = 2 ] && return 2 - # Wait for children to finish too if this is a daemon that forks - # and if the daemon is only ever run from this initscript. - # If the above conditions are not satisfied then add some other code - # that waits for the process to drop all resources that could be - # needed by services started subsequently. A last resort is to - # sleep for some time. - start-stop-daemon --stop --quiet --oknodo --retry=0/30/KILL/5 \ - --exec $DAEMON - [ "$?" = 2 ] && return 2 - # Many daemons don't delete their pidfiles when they exit. - rm -f $PIDFILE - return "$RETVAL" -} - -case "$1" in -start) - [ "$VERBOSE" != no ] && log_daemon_msg "Starting $DESC" "$NAME" - do_start - case "$?" in - 0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;; - 2) [ "$VERBOSE" != no ] && log_end_msg 1 ;; - esac - ;; -stop) - [ "$VERBOSE" != no ] && log_daemon_msg "Stopping $DESC" "$NAME" - do_stop - case "$?" in - 0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;; - 2) [ "$VERBOSE" != no ] && log_end_msg 1 ;; - esac - ;; -status) - status_of_proc "$DAEMON" "$NAME" && exit 0 || exit $? - ;; -restart|force-reload) - # - # If the "reload" option is implemented then remove the - # 'force-reload' alias - # - log_daemon_msg "Restarting $DESC" "$NAME" - do_stop - case "$?" in - 0|1) - do_start - case "$?" in - 0) log_end_msg 0 ;; - 1) log_end_msg 1 ;; # Old process is still running - *) log_end_msg 1 ;; # Failed to start - esac - ;; - *) - # Failed to stop - log_end_msg 1 - ;; - esac - ;; -*) - echo "Usage: $SCRIPTNAME {start|stop|status|restart|force-reload}" >&2 - exit 3 - ;; -esac - -exit 0 -``` - * Make sure that /etc/init.d/mattermost is executable - * ``` sudo chmod +x /etc/init.d/mattermost``` -1. On reboot, systemd will generate a unit file from the headers in this init script and install it in `/run/systemd/generator.late/` - -## Set up Nginx Server -1. For the purposes of this guide we will assume this server has an IP address of 10.10.10.3 -1. We use Nginx for proxying request to the Mattermost Server. The main benefits are: - * SSL termination - * http to https redirect - * Port mapping :80 to :8065 - * Standard request logs -1. Install Nginx on Debian with - * ``` sudo apt-get install nginx``` -1. Verify Nginx is running - * ``` curl http://10.10.10.3``` - * You should see a *Welcome to nginx!* page -1. You can manage Nginx with the following commands - * ``` sudo service nginx stop``` - * ``` sudo service nginx start``` - * ``` sudo service nginx restart``` -1. Map a FQDN (fully qualified domain name) like **mattermost.example.com** to point to the Nginx server. -1. Configure Nginx to proxy connections from the internet to the Mattermost Server - * Create a configuration for Mattermost - * ``` sudo touch /etc/nginx/sites-available/mattermost``` - * Below is a sample configuration with the minimum settings required to configure Mattermost -``` - server { - server_name mattermost.example.com; - - location / { - client_max_body_size 50M; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Frame-Options SAMEORIGIN; - proxy_pass http://10.10.10.2:8065; - } - } -``` - * Remove the existing file with - * ``` sudo rm /etc/nginx/sites-enabled/default``` - * Link the mattermost config by typing: - * ```sudo ln -s /etc/nginx/sites-available/mattermost /etc/nginx/sites-enabled/mattermost``` - * Restart Nginx by typing: - * ``` sudo service nginx restart``` - * Verify you can see Mattermost thru the proxy by typing: - * ``` curl http://localhost``` - * You should see a page titles *Mattermost - Signup* - -## Set up Nginx with SSL (Recommended) -1. You will need a SSL cert from a certificate authority. -1. For simplicity we will generate a test certificate. - * ``` mkdir ~/cert``` - * ``` cd ~/cert``` - * ``` sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout mattermost.key -out mattermost.crt``` - * Input the following info -``` - Country Name (2 letter code) [AU]:US - State or Province Name (full name) [Some-State]:California - Locality Name (eg, city) []:Palo Alto - Organization Name (eg, company) [Internet Widgits Pty Ltd]:Example LLC - Organizational Unit Name (eg, section) []: - Common Name (e.g. server FQDN or YOUR name) []:mattermost.example.com - Email Address []:admin@mattermost.example.com -``` -1. Run `openssl dhparam -out dhparam.pem 4096` (it will take some time). -1. Modify the file at `/etc/nginx/sites-available/mattermost` and add the following lines: -``` - server { - listen 80; - server_name mattermost.example.com; - return 301 https://$server_name$request_uri; - } - - server { - listen 443 ssl; - server_name mattermost.example.com; - - ssl on; - ssl_certificate /home/ubuntu/cert/mattermost.crt; - ssl_certificate_key /home/ubuntu/cert/mattermost.key; - ssl_dhparam /home/ubuntu/cert/dhparam.pem; - ssl_session_timeout 5m; - ssl_protocols TLSv1 TLSv1.1 TLSv1.2; - ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH'; - ssl_prefer_server_ciphers on; - ssl_session_cache shared:SSL:10m; - - location / { - gzip off; - proxy_set_header X-Forwarded-Ssl on; - client_max_body_size 50M; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Frame-Options SAMEORIGIN; - proxy_pass http://10.10.10.2:8065; - } - } -``` - - -## Finish Mattermost Server setup -1. Navigate to https://mattermost.example.com and create a team and user. -1. The first user in the system is automatically granted the `system_admin` role, which gives you access to the System Console. -1. From the `town-square` channel click the dropdown and choose the `System Console` option -1. Update Email Settings. We recommend using an email sending service. The example below assumes AmazonSES. - * Set *Send Email Notifications* to true - * Set *Require Email Verification* to true - * Set *Feedback Name* to `No-Reply` - * Set *Feedback Email* to `mattermost@example.com` - * Set *SMTP Username* to `AFIADTOVDKDLGERR` - * Set *SMTP Password* to `DFKJoiweklsjdflkjOIGHLSDFJewiskdjf` - * Set *SMTP Server* to `email-smtp.us-east-1.amazonaws.com` - * Set *SMTP Port* to `465` - * Set *Connection Security* to `TLS` - * Save the Settings -1. Update File Settings - * Change *Local Directory Location* from `./data/` to `/mattermost/data` -1. Update Log Settings. - * Set *Log to The Console* to false -1. Update Rate Limit Settings. - * Set *Vary By Remote Address* to false - * Set *Vary By HTTP Header* to X-Real-IP -1. Feel free to modify other settings. -1. Restart the Mattermost Service by typing: - * ``` sudo restart mattermost``` diff --git a/doc/install/Production-RHEL6.md b/doc/install/Production-RHEL6.md deleted file mode 100644 index d73295ebc..000000000 --- a/doc/install/Production-RHEL6.md +++ /dev/null @@ -1,231 +0,0 @@ -# Production Installation on Red Hat Enterprise Linux 6.6 - -## Install Red Hat Enterprise Linux (x64) 6.6 -1. Set up 3 machines with RHEL with 2GB of RAM or more. The servers will be used for the Load Balancer, Mattermost (this must be x64 to use pre-built binaries), and Database. - - **Optional:** You can also use a single machine for all 3 components in this install guide, depending on the standards of your data center. -2. Make sure the system is up to date with the most recent security patches. - * ``` sudo yum update``` - * ``` sudo yum upgrade``` - -## Set up Database Server -1. For the purposes of this guide we will assume this server has an IP address of `10.10.10.1` - - **Optional:** if installing on the same machine substitute `10.10.10.1` with `127.0.0.1` -1. Install PostgreSQL 9.4+ (or MySQL 5.6+) - * ``` sudo yum install http://yum.postgresql.org/9.4/redhat/rhel-6-x86_64/pgdg-redhat94-9.4-1.noarch.rpm``` - * ``` sudo yum install postgresql94-server postgresql94-contrib``` - * ``` sudo service postgresql-9.4 initdb``` - * ``` sudo chkconfig postgresql-9.4 on``` - * ``` sudo service postgresql-9.4 start``` -1. PostgreSQL created a user account called `postgres`. You will need to log into that account with: - * ``` sudo -i -u postgres``` -1. You can get a PostgreSQL prompt by typing: - * ``` psql``` -1. Create the Mattermost database by typing: - * ```postgres=# CREATE DATABASE mattermost;``` -1. Create the Mattermost user by typing: - * ```postgres=# CREATE USER mmuser WITH PASSWORD 'mmuser_password';``` -1. Grant the user access to the Mattermost database by typing: - * ```postgres=# GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser;``` -1. You can exit out of PostgreSQL by typing: - * ```postgres=# \q``` -1. You can exit the Postgres account by typing: - * ``` exit``` -1. Allow Postgres to listen on all assigned IP Addresses: - * ```sudo vi /var/lib/pgsql/9.4/data/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 /var/lib/pgsql/9.4/data/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 service postgresql-9.4 restart``` -1. Attempt to connect with the new created user to verify everything looks good: - * ```psql --host=10.10.10.1 --dbname=mattermost --username=mmuser --password``` - * ```mattermost=> \q``` - - -## 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. Download the latest Mattermost Server by typing: - * ``` wget https://github.com/mattermost/platform/releases/download/v1.3.0/mattermost.tar.gz``` -1. Install Mattermost under `/opt` - * Unzip the Mattermost Server by typing: - * ``` tar -xvzf mattermost.tar.gz``` - * ``` sudo mv mattermost /opt``` -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 `/opt/mattermost/data`. - * Create the directory by typing: - * ``` sudo mkdir -p /opt/mattermost/data``` -1. Create a system user and group called mattermost that will run this service: - * ``` sudo useradd -r mattermost -U``` - * Set the Mattermost account as the directory owner by typing: - * ``` sudo chown -R mattermost:mattermost /opt/mattermost``` - * ``` sudo chmod -R g+w /opt/mattermost``` - * Add yourself to the mattermost group to ensure you can edit these files: - * ``` sudo usermod -a -G mattermost USERNAME``` -1. Configure Mattermost Server by editing the `config.json` file at `/opt/mattermost/config` - * ``` cd /opt/mattermost/config``` - * Edit the file by typing: - * ``` sudo vi config.json``` - * replace `DriverName": "mysql"` with `DriverName": "postgres"` - * replace `"DataSource": "mmuser:mostest@tcp(dockerhost:3306)/mattermost_test?charset=utf8mb4,utf8"` with `"DataSource": "postgres://mmuser:mmuser_password@10.10.10.1:5432/mattermost?sslmode=disable&connect_timeout=10"` - * Optionally you may continue to edit configuration settings in `config.json` or use the System Console described in a later section to finish the configuration. -1. Test the Mattermost Server - * ``` cd /opt/mattermost/bin``` - * Run the Mattermost Server by typing: - * ``` sudo su mattermost``` - * ``` ./platform``` - * You should see a console log like `Server is listening on :8065` letting you know the service is running. - * Stop the server for now by typing `Ctrl-C` -1. Setup Mattermost to use the Upstart daemon which handles supervision of the Mattermost process. - * ``` sudo touch /etc/init/mattermost.conf``` - * ``` sudo vi /etc/init/mattermost.conf``` - * Copy the following lines into `/etc/init/mattermost.conf` -``` -start on runlevel [2345] -stop on runlevel [016] -respawn -chdir /opt/mattermost -exec bin/platform -``` - * You can manage the process by typing: - * ``` sudo start mattermost``` - * Verify the service is running by typing: - * ``` curl http://10.10.10.2:8065``` - * You should see a page titles *Mattermost - Signup* - * You can also stop the process by running the command ` sudo stop mattermost`, but we will skip this step for now. - -## Set up Nginx Server -1. For the purposes of this guide we will assume this server has an IP address of `10.10.10.3` -1. We use Nginx for proxying request to the Mattermost Server. The main benefits are: - * SSL termination - * HTTP to HTTPS redirect - * Port mapping :80 to :8065 - * Standard request logs -1. Install Nginx on RHEL with - * ``` sudo vi /etc/yum.repos.d/nginx.repo``` - * Copy the below into the file -``` -[nginx] -name=nginx repo -baseurl=http://nginx.org/packages/rhel/6/$basearch/ -gpgcheck=0 -enabled=1 -``` - * ``` sudo yum install nginx.x86_64``` - * ``` sudo service nginx start``` - * ``` sudo chkconfig nginx on``` -1. Verify Nginx is running - * ``` curl http://10.10.10.3``` - * You should see a *Welcome to nginx!* page -1. Map a FQDN (fully qualified domain name) like **mattermost.example.com** to point to the Nginx server. -1. Configure Nginx to proxy connections from the internet to the Mattermost Server - * Create a configuration for Mattermost - * ``` sudo touch /etc/nginx/conf.d/mattermost.conf``` - * Below is a sample configuration with the minimum settings required to configure Mattermost -``` - server { - server_name mattermost.example.com; - - location / { - client_max_body_size 50M; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Frame-Options SAMEORIGIN; - proxy_pass http://10.10.10.2:8065; - } - } -``` - * Remove the existing file with: - * ``` sudo mv /etc/nginx/conf.d/default.conf /etc/nginx/conf.d/default.conf.bak``` - * Restart Nginx by typing: - * ``` sudo service nginx restart``` - * Verify you can see Mattermost thru the proxy by typing: - * ``` curl http://localhost``` - * You should see a page titles *Mattermost - Signup* - * Not seeing the page? Look for errors with ``` sudo cat /var/log/audit/audit.log | grep nginx | grep denied``` - * **Optional** if you're running on the same server as the Mattermost server and see 502 errors you may need to run `sudo setsebool -P httpd_can_network_connect true` because SELinux is preventing the connection - -## Set up Nginx with SSL (Recommended) -1. You will need a SSL cert from a certificate authority. -1. For simplicity we will generate a test certificate. - * ``` mkdir /top/mattermost/cert``` - * ``` cd /top/mattermost/cert``` - * ``` sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout mattermost.key -out mattermost.crt``` - * Input the following info -``` - Country Name (2 letter code) [AU]:US - State or Province Name (full name) [Some-State]:California - Locality Name (eg, city) []:Palo Alto - Organization Name (eg, company) [Internet Widgits Pty Ltd]:Example LLC - Organizational Unit Name (eg, section) []: - Common Name (e.g. server FQDN or YOUR name) []:mattermost.example.com - Email Address []:admin@mattermost.example.com -``` -1. Run `openssl dhparam -out dhparam.pem 4096` (it will take some time). -1. Modify the file at `/etc/nginx/conf.d/mattermost.conf` and add the following lines -``` - server { - listen 80; - server_name mattermost.example.com; - return 301 https://$server_name$request_uri; - } - - server { - listen 443 ssl; - server_name mattermost.example.com; - - ssl on; - ssl_certificate /home/ubuntu/cert/mattermost.crt; - ssl_certificate_key /home/ubuntu/cert/mattermost.key; - ssl_dhparam /home/ubuntu/cert/dhparam.pem; - ssl_session_timeout 5m; - ssl_protocols TLSv1 TLSv1.1 TLSv1.2; - ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH'; - ssl_prefer_server_ciphers on; - ssl_session_cache shared:SSL:10m; - - location / { - gzip off; - proxy_set_header X-Forwarded-Ssl on; - client_max_body_size 50M; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Frame-Options SAMEORIGIN; - proxy_pass http://10.10.10.2:8065; - } - } -``` - -## Finish Mattermost Server setup -1. Navigate to `https://mattermost.example.com` and create a team and user. -1. The first user in the system is automatically granted the `system_admin` role, which gives you access to the System Console. -1. From the `town-square` channel click the dropdown and choose the `System Console` option -1. Update Email Settings. We recommend using an email sending service. The example below assumes AmazonSES. - * Set *Send Email Notifications* to true - * Set *Require Email Verification* to true - * Set *Feedback Name* to `No-Reply` - * Set *Feedback Email* to `mattermost@example.com` - * Set *SMTP Username* to `AFIADTOVDKDLGERR` - * Set *SMTP Password* to `DFKJoiweklsjdflkjOIGHLSDFJewiskdjf` - * Set *SMTP Server* to `email-smtp.us-east-1.amazonaws.com` - * Set *SMTP Port* to `465` - * Set *Connection Security* to `TLS` - * Save the Settings -1. Update File Settings: - * Change *Local Directory Location* from `./data/` to `/opt/mattermost/data` -1. Update Log Settings: - * Set *Log to The Console* to `false` -1. Update Rate Limit Settings: - * Set *Vary By Remote Address* to false - * Set *Vary By HTTP Header* to X-Real-IP -1. Feel free to modify other settings -1. Restart the Mattermost Service by typing: - * ``` sudo restart mattermost``` diff --git a/doc/install/Production-RHEL7.md b/doc/install/Production-RHEL7.md deleted file mode 100644 index 4e003dd46..000000000 --- a/doc/install/Production-RHEL7.md +++ /dev/null @@ -1,238 +0,0 @@ -# Production Installation on Red Hat Enterprise Linux 7.1+ - -## Install Red Hat Enterprise Linux (x64) 7.1+ -1. Set up 3 machines with RHEL with 2GB of RAM or more. The servers will be used for the Load Balancer, Mattermost (this must be x64 to use pre-built binaries), and Database. - - **Optional:** You can also use a single machine for all 3 components in this install guide, depending on the standards of your data center. -2. Make sure the system is up to date with the most recent security patches. - * ``` sudo yum update``` - * ``` sudo yum upgrade``` - -## Set up Database Server -1. For the purposes of this guide we will assume this server has an IP address of `10.10.10.1` - - **Optional:** if installing on the same machine substitute `10.10.10.1` with `127.0.0.1` -1. Install PostgreSQL 9.4+ (or MySQL 5.6+) - * ``` sudo yum install http://yum.postgresql.org/9.4/redhat/rhel-6-x86_64/pgdg-redhat94-9.4-1.noarch.rpm``` - * ``` sudo yum install postgresql94-server postgresql94-contrib``` - * ``` sudo /usr/pgsql-9.4/bin/postgresql94-setup initdb``` - * ``` sudo systemctl enable postgresql-9.4.service``` - * ``` sudo systemctl start postgresql-9.4.service``` -1. PostgreSQL created a user account called `postgres`. You will need to log into that account with: - * ``` sudo -i -u postgres``` -1. You can get a PostgreSQL prompt by typing: - * ``` psql``` -1. Create the Mattermost database by typing: - * ```postgres=# CREATE DATABASE mattermost;``` -1. Create the Mattermost user by typing: - * ```postgres=# CREATE USER mmuser WITH PASSWORD 'mmuser_password';``` -1. Grant the user access to the Mattermost database by typing: - * ```postgres=# GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser;``` -1. You can exit out of PostgreSQL by typing: - * ```postgres=# \q``` -1. You can exit the Postgres account by typing: - * ``` exit``` -1. Allow Postgres to listen on all assigned IP Addresses: - * ```sudo vi /var/lib/pgsql/9.4/data/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 /var/lib/pgsql/9.4/data/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 systemctl reload postgresql-9.4.service``` -1. Attempt to connect with the new created user to verify everything looks good: - * ```psql --host=10.10.10.1 --dbname=mattermost --username=mmuser --password``` - * ```mattermost=> \q``` - - -## 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. Download the latest Mattermost Server by typing: - * ``` wget https://github.com/mattermost/platform/releases/download/v1.3.0/mattermost.tar.gz``` -1. Install Mattermost under `/opt` - * Unzip the Mattermost Server by typing: - * ``` tar -xvzf mattermost.tar.gz``` - * ``` sudo mv mattermost /opt``` -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 `/opt/mattermost/data`. - * Create the directory by typing: - * ``` sudo mkdir -p /opt/mattermost/data``` -1. Create a system user and group called mattermost that will run this service: - * ``` sudo useradd -r mattermost -U``` - * Set the Mattermost account as the directory owner by typing: - * ``` sudo chown -R mattermost:mattermost /opt/mattermost``` - * ``` sudo chmod -R g+w /opt/mattermost``` - * Add yourself to the mattermost group to ensure you can edit these files: - * ``` sudo usermod -aG mattermost USERNAME``` -1. Configure Mattermost Server by editing the `config.json` file at `/opt/mattermost/config` - * ``` cd /opt/mattermost/config``` - * Edit the file by typing: - * ``` sudo vi config.json``` - * replace `DriverName": "mysql"` with `DriverName": "postgres"` - * replace `"DataSource": "mmuser:mostest@tcp(dockerhost:3306)/mattermost_test?charset=utf8mb4,utf8"` with `"DataSource": "postgres://mmuser:mmuser_password@10.10.10.1:5432/mattermost?sslmode=disable&connect_timeout=10"` - * Optionally you may continue to edit configuration settings in `config.json` or use the System Console described in a later section to finish the configuration. -1. Test the Mattermost Server - * ``` cd /opt/mattermost/bin``` - * Run the Mattermost Server by typing: - * ``` ./platform``` - * You should see a console log like `Server is listening on :8065` letting you know the service is running. - * Stop the server for now by typing `Ctrl-C` -1. Set up Mattermost to use the systemd init daemon which handles supervision of the Mattermost process: - * ``` sudo touch /etc/systemd/system/mattermost.service``` - * ``` sudo vi /etc/systemd/system/mattermost.service``` - * Copy the following lines into `/etc/systemd/system/mattermost.service` -``` -[Unit] -Description=Mattermost -After=syslog.target network.target - -[Service] -Type=simple -WorkingDirectory=/opt/mattermost/bin -User=mattermost -ExecStart=/opt/mattermost/bin/platform -PIDFile=/var/spool/mattermost/pid/master.pid - -[Install] -WantedBy=multi-user.target -``` - * Make sure the service is executable with ``` sudo chmod 664 /etc/systemd/system/mattermost.service``` - * Reload the services with `sudo systemctl daemon-reload` - * Start Mattermost service with `sudo systemctl start mattermost.service` - * `sudo chkconfig mattermost on` - * Start server on reboot `sudo systemctl enable mattermost.service` - - -## Set up Nginx Server -1. For the purposes of this guide we will assume this server has an IP address of `10.10.10.3` -1. We use Nginx for proxying request to the Mattermost Server. The main benefits are: - * SSL termination - * HTTP to HTTPS redirect - * Port mapping :80 to :8065 - * Standard request logs -1. Install Nginx on RHEL with - * ``` sudo vi /etc/yum.repos.d/nginx.repo``` - * Copy the below into the file -``` -[nginx] -name=nginx repo -baseurl=http://nginx.org/packages/rhel/7/$basearch/ -gpgcheck=0 -enabled=1 -``` - * ``` sudo yum install nginx.x86_64``` - * ``` sudo service nginx start``` - * ``` sudo chkconfig nginx on``` -1. Verify Nginx is running - * ``` curl http://10.10.10.3``` - * You should see a *Welcome to nginx!* page -1. Map a FQDN (fully qualified domain name) like **mattermost.example.com** to point to the Nginx server. -1. Configure Nginx to proxy connections from the internet to the Mattermost Server - * Create a configuration for Mattermost - * ``` sudo touch /etc/nginx/conf.d/mattermost.conf``` - * Below is a sample configuration with the minimum settings required to configure Mattermost -``` - server { - server_name mattermost.example.com; - - location / { - client_max_body_size 50M; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Frame-Options SAMEORIGIN; - proxy_pass http://10.10.10.2:8065; - } - } -``` - * Remove the existing file with: - * ``` sudo mv /etc/nginx/conf.d/default.conf /etc/nginx/conf.d/default.conf.bak``` - * Restart Nginx by typing: - * ``` sudo service nginx restart``` - * Verify you can see Mattermost thru the proxy by typing: - * ``` curl http://localhost``` - * You should see a page titles *Mattermost - Signup* - * Not seeing the page? Look for errors with ``` sudo cat /var/log/audit/audit.log | grep nginx | grep denied``` - * **Optional** if you're running on the same server as the Mattermost server and see 502 errors you may need to run `sudo setsebool -P httpd_can_network_connect true` because SELinux is preventing the connection - -## Set up Nginx with SSL (Recommended) -1. You will need a SSL cert from a certificate authority. -1. For simplicity we will generate a test certificate. - * ``` mkdir /top/mattermost/cert``` - * ``` cd /top/mattermost/cert``` - * ``` sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout mattermost.key -out mattermost.crt``` - * Input the following info -``` - Country Name (2 letter code) [AU]:US - State or Province Name (full name) [Some-State]:California - Locality Name (eg, city) []:Palo Alto - Organization Name (eg, company) [Internet Widgits Pty Ltd]:Example LLC - Organizational Unit Name (eg, section) []: - Common Name (e.g. server FQDN or YOUR name) []:mattermost.example.com - Email Address []:admin@mattermost.example.com -``` -1. Run `openssl dhparam -out dhparam.pem 4096` (it will take some time). -1. Modify the file at `/etc/nginx/conf.d/mattermost.conf` and add the following lines -``` - server { - listen 80; - server_name mattermost.example.com; - return 301 https://$server_name$request_uri; - } - - server { - listen 443 ssl; - server_name mattermost.example.com; - - ssl on; - ssl_certificate /home/ubuntu/cert/mattermost.crt; - ssl_certificate_key /home/ubuntu/cert/mattermost.key; - ssl_dhparam /home/ubuntu/cert/dhparam.pem; - ssl_session_timeout 5m; - ssl_protocols TLSv1 TLSv1.1 TLSv1.2; - ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH'; - ssl_prefer_server_ciphers on; - ssl_session_cache shared:SSL:10m; - - location / { - gzip off; - proxy_set_header X-Forwarded-Ssl on; - client_max_body_size 50M; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Frame-Options SAMEORIGIN; - proxy_pass http://10.10.10.2:8065; - } - } -``` - -## Finish Mattermost Server setup -1. Navigate to `https://mattermost.example.com` and create a team and user. -1. The first user in the system is automatically granted the `system_admin` role, which gives you access to the System Console. -1. From the `town-square` channel click the dropdown and choose the `System Console` option -1. Update Email Settings. We recommend using an email sending service. The example below assumes AmazonSES. - * Set *Send Email Notifications* to true - * Set *Require Email Verification* to true - * Set *Feedback Name* to `No-Reply` - * Set *Feedback Email* to `mattermost@example.com` - * Set *SMTP Username* to `AFIADTOVDKDLGERR` - * Set *SMTP Password* to `DFKJoiweklsjdflkjOIGHLSDFJewiskdjf` - * Set *SMTP Server* to `email-smtp.us-east-1.amazonaws.com` - * Set *SMTP Port* to `465` - * Set *Connection Security* to `TLS` - * Save the Settings -1. Update File Settings: - * Change *Local Directory Location* from `./data/` to `/opt/mattermost/data` -1. Update Log Settings: - * Set *Log to The Console* to `false` -1. Update Rate Limit Settings: - * Set *Vary By Remote Address* to false - * Set *Vary By HTTP Header* to X-Real-IP -1. Feel free to modify other settings -1. Restart the Mattermost Service by typing: - * ``` sudo restart mattermost``` diff --git a/doc/install/Production-Ubuntu.md b/doc/install/Production-Ubuntu.md deleted file mode 100644 index 8d3565d4a..000000000 --- a/doc/install/Production-Ubuntu.md +++ /dev/null @@ -1,215 +0,0 @@ -# Production Installation on Ubuntu 14.04 LTS - -## Install Ubuntu Server (x64) 14.04 LTS -1. Set up 3 machines with Ubuntu 14.04 with 2GB of RAM or more. The servers will be used for the Load Balancer, Mattermost (this must be x64 to use pre-built binaries), and Database. - - **Optional:** You can also use a single machine for all 3 components in this install guide, depending on the standards of your data center. -2. Make sure the system is up to date with the most recent security patches. - * ``` sudo apt-get update``` - * ``` sudo apt-get upgrade``` - -## Set up Database Server -1. For the purposes of this guide we will assume this server has an IP address of 10.10.10.1 -1. Install PostgreSQL 9.3+ (or MySQL 5.6+) - * ``` sudo apt-get install postgresql postgresql-contrib``` -1. PostgreSQL created a user account called `postgres`. You will need to log into that account with: - * ``` sudo -i -u postgres``` -1. You can get a PostgreSQL prompt by typing: - * ``` psql``` -1. Create the Mattermost database by typing: - * ```postgres=# CREATE DATABASE mattermost;``` -1. Create the Mattermost user by typing: - * ```postgres=# CREATE USER mmuser WITH PASSWORD 'mmuser_password';``` -1. Grant the user access to the Mattermost database by typing: - * ```postgres=# GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser;``` -1. You can exit out of PostgreSQL by typing: - * ```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``` -1. Attempt to connect with the new created user to verify everything looks good - * ```psql --host=10.10.10.1 --dbname=mattermost --username=mmuser --password``` - * ```mattermost=> \q``` - - -## 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.4.0/mattermost.tar.gz``` -1. Unzip the Mattermost Server by typing: - * ``` tar -xvzf mattermost.tar.gz``` -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` - * ``` cd ~/mattermost/config``` - * Edit the file by typing: - * ``` vi config.json``` - * replace `DriverName": "mysql"` with `DriverName": "postgres"` - * replace `"DataSource": "mmuser:mostest@tcp(dockerhost:3306)/mattermost_test?charset=utf8mb4,utf8"` with `"DataSource": "postgres://mmuser:mmuser_password@10.10.10.1:5432/mattermost?sslmode=disable&connect_timeout=10"` - * Optionally you may continue to edit configuration settings in `config.json` or use the System Console described in a later section to finish the configuration. -1. Test the Mattermost Server - * ``` cd ~/mattermost/bin``` - * Run the Mattermost Server by typing: - * ``` ./platform``` - * You should see a console log like `Server is listening on :8065` letting you know the service is running. - * Stop the server for now by typing `ctrl-c` -1. Setup Mattermost to use the Upstart daemon which handles supervision of the Mattermost process. - * ``` sudo touch /etc/init/mattermost.conf``` - * ``` sudo vi /etc/init/mattermost.conf``` - * Copy the following lines into `/etc/init/mattermost.conf` -``` -start on runlevel [2345] -stop on runlevel [016] -respawn -chdir /home/ubuntu/mattermost -setuid ubuntu -exec bin/platform -``` - * You can manage the process by typing: - * ``` sudo start mattermost``` - * Verify the service is running by typing: - * ``` curl http://10.10.10.2:8065``` - * You should see a page titles *Mattermost - Signup* - * You can also stop the process by running the command ` sudo stop mattermost`, but we will skip this step for now. - -## Set up Nginx Server -1. For the purposes of this guide we will assume this server has an IP address of 10.10.10.3 -1. We use Nginx for proxying request to the Mattermost Server. The main benefits are: - * SSL termination - * http to https redirect - * Port mapping :80 to :8065 - * Standard request logs -1. Install Nginx on Ubuntu with - * ``` sudo apt-get install nginx``` -1. Verify Nginx is running - * ``` curl http://10.10.10.3``` - * You should see a *Welcome to nginx!* page -1. You can manage Nginx with the following commands - * ``` sudo service nginx stop``` - * ``` sudo service nginx start``` - * ``` sudo service nginx restart``` -1. Map a FQDN (fully qualified domain name) like **mattermost.example.com** to point to the Nginx server. -1. Configure Nginx to proxy connections from the internet to the Mattermost Server - * Create a configuration for Mattermost - * ``` sudo touch /etc/nginx/sites-available/mattermost``` - * Below is a sample configuration with the minimum settings required to configure Mattermost -``` - server { - server_name mattermost.example.com; - - location / { - client_max_body_size 50M; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Frame-Options SAMEORIGIN; - proxy_pass http://10.10.10.2:8065; - } - } -``` - * Remove the existing file with - * ``` sudo rm /etc/nginx/sites-enabled/default``` - * Link the mattermost config by typing: - * ```sudo ln -s /etc/nginx/sites-available/mattermost /etc/nginx/sites-enabled/mattermost``` - * Restart Nginx by typing: - * ``` sudo service nginx restart``` - * Verify you can see Mattermost thru the proxy by typing: - * ``` curl http://localhost``` - * You should see a page titles *Mattermost - Signup* - -## Set up Nginx with SSL (Recommended) -1. You will need a SSL cert from a certificate authority. -2. For simplicity we will generate a test certificate. - * ``` mkdir ~/cert``` - * ``` cd ~/cert``` - * ``` sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout mattermost.key -out mattermost.crt``` - * Input the following info -``` - Country Name (2 letter code) [AU]:US - State or Province Name (full name) [Some-State]:California - Locality Name (eg, city) []:Palo Alto - Organization Name (eg, company) [Internet Widgits Pty Ltd]:Example LLC - Organizational Unit Name (eg, section) []: - Common Name (e.g. server FQDN or YOUR name) []:mattermost.example.com - Email Address []:admin@mattermost.example.com -``` -3. Run `openssl dhparam -out dhparam.pem 4096` (it will take some time). -4. Modify the file at `/etc/nginx/sites-available/mattermost` and add the following lines: -``` - server { - listen 80; - server_name mattermost.example.com; - return 301 https://$server_name$request_uri; - } - - server { - listen 443 ssl; - server_name mattermost.example.com; - - ssl on; - ssl_certificate /home/ubuntu/cert/mattermost.crt; - ssl_certificate_key /home/ubuntu/cert/mattermost.key; - ssl_dhparam /home/ubuntu/cert/dhparam.pem; - ssl_session_timeout 5m; - ssl_protocols TLSv1 TLSv1.1 TLSv1.2; - ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH'; - ssl_prefer_server_ciphers on; - ssl_session_cache shared:SSL:10m; - - location / { - gzip off; - proxy_set_header X-Forwarded-Ssl on; - client_max_body_size 50M; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Frame-Options SAMEORIGIN; - proxy_pass http://10.10.10.2:8065; - } - } -``` - - -## Finish Mattermost Server setup -1. Navigate to https://mattermost.example.com and create a team and user. -1. The first user in the system is automatically granted the `system_admin` role, which gives you access to the System Console. -1. From the `town-square` channel click the dropdown and choose the `System Console` option -1. Update Email Settings. We recommend using an email sending service. The example shows how an Amazon SES setup might look (sample credentials shown below are not real). - * Set *Send Email Notifications* to true - * Set *Require Email Verification* to true - * Set *Feedback Name* to `No-Reply` - * Set *Feedback Email* to `mattermost@example.com` - * Set *SMTP Username* to `AFIADTOVDKDLGERR` - * Set *SMTP Password* to `DFKJoiweklsjdflkjOIGHLSDFJewiskdjf` - * Set *SMTP Server* to `email-smtp.us-east-1.amazonaws.com` - * Set *SMTP Port* to `465` - * Set *Connection Security* to `TLS` - * Save the Settings -1. Update File Settings - * Change *Local Directory Location* from `./data/` to `/mattermost/data` -1. Update Log Settings. - * Set *Log to The Console* to false -1. Update Rate Limit Settings. - * Set *Vary By Remote Address* to false - * Set *Vary By HTTP Header* to X-Real-IP -1. Feel free to modify other settings. -1. Restart the Mattermost Service by typing: - * ``` sudo restart mattermost``` diff --git a/doc/install/Release-Numbering.md b/doc/install/Release-Numbering.md deleted file mode 100644 index 41aba109f..000000000 --- a/doc/install/Release-Numbering.md +++ /dev/null @@ -1,23 +0,0 @@ -# Mattermost Release Schedule and Numbering - -## Release Schedule - -Mattermost releases stable builds monthly on the 16th in [binary form](https://github.com/mattermost/platform/releases) - -## Release Numbering - -Mattermost numbers its stable releases based on the following format: - - `[Version Number].[Major Build Number].[Minor Build Number]` - -Version Number: - -- Indicates a major system release (e.g. 1.x.x, 2.x.x) - -Major Build Number: - -- Indicates significant new functionality, (e.g. 0.5.x, 0.6.x, 0.7.x) - -Minor Build Number: - -- Indicates a bug fix or security release (e.g. 1.2.5, 1.2.6) diff --git a/doc/install/Requirements.md b/doc/install/Requirements.md deleted file mode 100644 index 162caf90d..000000000 --- a/doc/install/Requirements.md +++ /dev/null @@ -1,91 +0,0 @@ -## Software Requirements - -### Web Client - -Supported Operating Systems and Browsers for the Mattermost Web Client include: - -- 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 9+, Chrome 43+) -- Android 5 and higher (Chrome 43+) - -### Email Client - -Supported Email Clients for rendering Mattermost email notifications include: - -Web based clients: -- Gmail -- Office 365 -- Outlook -- Yahoo -- AOL - -Desktop Clients: -- Apple Mail version 7+ -- Outlook 2016+ -- Thunderbird 38.2+ - -Mobile Clients: -- Gmail Mobile App (Android, iOS) -- iOS Mail App (iOS 7+) -- Blackberry Mail App (OS version 4+) - -### Server - -Supported Operating Systems for the Mattermost Server include: - -- Ubuntu -- Debian -- CentOS -- RedHat Enterprise Linux -- Oracle Linux - -The Mattermost roadmap does not currently include production support for Fedora, FreeBSD or Arch Linux. - -## Hardware Requirements - -Mattermost offers both real-time communication and file sharing. CPU and Memory requirements are typically driven by the number of concurrent users using real-time messaging. Storage requirements are typically driven by number and size of files shared. - -The below guidelines offer estimates based on real world usage of Mattermost in multi-team configurations ranging from 10-100 users per team. - -### CPU - -- 2 cores is the recommended number of cores and supports up to 250 users -- 4 cores supports up to 1,000 users -- 8 cores supports up to 2,500 users -- 16 cores supports up to 5,000 users -- 32 cores supports up to 10,000 users -- 64 cores supports up to 20,000 users - -### Memory - -- 2GB RAM is the recommended memory size and supports up to 50 users -- 4GB RAM supports up to 500 users -- 8GB RAM supports up to 1,000 users -- 16GB RAM supports up to 2,000 users -- 32GB RAM supports up to 4,000 users -- 64GB RAM supports up to 8,000 users -- 128GB RAM supports up to 16,000 users - -### Storage - -To estimate initial storage requirements, begin with a Mattermost server approximately 600 MB to 800 MB in size including operating system and database, then add the multiplied product of: - -- Estimated storage per user per month (see below), multipled by 12 months in a year -- Estimated mean average number of users in a year -- A 1-2x safety factor - -**Estimated storage per user per month** - -File usage per user varies significantly across industries. The below benchmarks are recommended: - -- **Low usage teams** (1-5 MB/user/month) - Primarily use text-messages and links to communicate. Examples would include software development teams that heavily use web-based document creation and management tools, and therefore rarely upload files to the server. - -- **Medium usage teams** (5-25 MB/user/month) - Use a mix of text-messages as well as shared documents and images to communicate. Examples might include business teams that may commonly drag and drop screenshots, PDFs and Microsoft Office documents into Mattermost for sharing and review. - -- **High usage teams** - (25-100 MB/user/month) - Heaviest utlization comes from teams uploading a high number of large files into Mattermost on a regular basis. Examples include creative teams who share and store artwork and media with tags and commentary in a pipeline production process. - -*Example:* A 30-person team with medium usage (5-25 MB/user/month) with a safety factor of 2x would require between 300 MB (30 users * 5 MB * 2x safety factor) and 1500 MB (30 users * 25 MB * 2x safety factor) of free space in the next year. - -It's recommended to review storage utilization at least quarterly to ensure adequate free space is available. diff --git a/doc/install/SMTP-Email-Setup.md b/doc/install/SMTP-Email-Setup.md deleted file mode 100644 index 7d9beae89..000000000 --- a/doc/install/SMTP-Email-Setup.md +++ /dev/null @@ -1,107 +0,0 @@ - -## SMTP Email Setup - -In product evaluation setups with single-container Docker instances, email is intentionally disabled. This allows account creation and system operation without having to set up email, but it also means email notification and password reset functionality aren't available. - -### How to enable email - -To enable email, configure an SMTP email service as follows: - -1. **Set up an SMTP email sending service** (if you don't yet have an SMTP service with credentials) - 1. Any SMTP email service can be used, you just need the following information: `Server Name`, `Port`, `SMTP Username`, and `SMTP Password`. - 2. If you don't have an SMTP service, here are simple instructions to set one up with [Amazon Simple Email Service (SES)](https://aws.amazon.com/ses/): - 2. Go to [Amazon SES console](https://console.aws.amazon.com/ses) then `SMTP Settings > Create My SMTP Credentials` - 3. Copy the `Server Name`, `Port`, `SMTP Username`, and `SMTP Password` for Step 2 below. - 4. From the `Domains` menu set up and verify a new domain, then enable `Generate DKIM Settings` for the domain. - 1. We recommend you set up _[Sender Policy Framework](https://en.wikipedia.org/wiki/Sender_Policy_Framework) (SPF)_ and/or _[Domain Keys Identified Mail](https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail) (DKIM)_ for your email domain. - 5. Choose an sender address like `mattermost@example.com` and click `Send a Test Email` to verify setup is working correctly. - -2. **Configure SMTP settings** - 1. Open the **System Console** by logging into an existing team and accessing "System Console" from the main menu. - 1. Alternatively, if a team doesn't yet exist, go to `http://dockerhost:8065/` in your browser, create a team, then from the main menu click **System Console** - 2. Go to the **Email Settings** tab and configure the following: - 1. **Allow Sign Up With Email:** `true` - 2. **Send Email Notifications:** `true` - 3. **Require Email Verification:** `true` - 4. **Notification Display Name:** Display name on email account sending notifications - 5. **Notification Email Address:** Email address displayed on email account used to send notifications - 6. **SMTP Username**: `SMTP Username` from Step 1 - 7. **SMTP Password**: `SMTP Password` from Step 1 - 8. **SMTP Server**: `SMTP Server` from Step 1 - 9. **SMTP Port**: `SMTP Port` from Step 1 - 10. **Connection Security**: `TLS (Recommended)` - 11. Then click **Save** - 12. Then click **Test Connection** - 13. If the test failed please look in **OTHER** > **Logs** for any errors that look like `[EROR] /api/v1/admin/test_email ...` - -### Known Good Sample Settings - -##### Amazon SES -* Set **SMTP Username** to **AKIASKLDSKDIWEOWE** -* Set **SMTP Password** to **AdskfjAKLSDJShflsdfjkakldADkjkjdfKAJDSlkjweiqQIWEOU** -* Set **SMTP Server** to **email-smtp.us-east-1.amazonaws.com** -* Set **SMTP Port** to **465** -* Set **Connection Security** to **TLS** - -##### Postfix -* Make sure Postfix is installed on the machine where Mattermost is installed -* Set **SMTP Username** to **(empty)** -* Set **SMTP Password** to **(empty)** -* Set **SMTP Server** to **localhost** -* Set **SMTP Port** to **25** -* Set **Connection Security** to **(empty)** - -##### Gmail -* Set **SMTP Username** to **your_email@gmail.com** -* Set **SMTP Password** to **your_password** -* Set **SMTP Server** to **smtp.gmail.com** -* Set **SMTP Port** to **587** -* Set **Connection Security** to **TLS** - -##### Office 365 -* Set **SMTP Username** to **Office 365 username** -* Set **SMTP Password** to **Office 365 password** -* Set **SMTP Server** to **smtp.office365.com** -* Set **SMTP Port** to **587** -* Set **Connection Security** to **TLS** - -##### Hotmail -* Set **SMTP Username** to **your_email@hotmail.com** -* Set **SMTP Password** to **your_password** -* Set **SMTP Server** to **smtp-mail.outlook.com** -* Set **SMTP Port** to **587** -* Set **Connection Security** to **STARTTLS** - - -### Troubleshooting SMTP - -#### Tip 1 -If you fill in **SMTP Username** and **SMTP Password** then you must set **Connection Security** to **TLS** or to **STARTTLS** - -#### Tip 2 -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`. - -#### Tip 3 -* Attempt to telnet to the email service to make sure the server is reachable. -* You must run the following commands from the same machine or virtual instance where `mattermost/bin/platform` is located. So if you're running Mattermost from docker you need to `docker exec -ti mattermost-dev /bin/bash` -* Telnet to the email server with `telnet mail.example.com 25`. If the command works you should see something like -``` -Trying 24.121.12.143... -Connected to mail.example.com. -220 mail.example.com NO UCE ESMTP -``` -* Then type something like `HELO <your mail server domain>`. If the command works you should see something like -``` -250-mail.example.com NO UCE -250-STARTTLS -250-PIPELINING -250 8BITMIME -``` diff --git a/doc/install/Troubleshooting.md b/doc/install/Troubleshooting.md deleted file mode 100644 index 05cac2f48..000000000 --- a/doc/install/Troubleshooting.md +++ /dev/null @@ -1,66 +0,0 @@ -# Mattermost Troubleshooting - -#### Important notes - -##### **DO NOT manipulate the Mattermost database** - - In particular, DO NOT delete data from the database, as Mattermost is designed to stop working if data integrity has been compromised. The system is designed to archive content continously and generally assumes data is never deleted. - - -#### Common Issues - -##### Lost System Administrator account - - 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. - -#### Mattermost Error Messages - -The following is a list of common error messages and solutions: - -###### `Please check connection, Mattermost unreachable. If issue persists, ask administrator to check WebSocket port.` -- Message appears in blue bar on team site. -- **Solution:** Check that [your websocket port is properly configured](https://github.com/mattermost/platform/blob/master/doc/install/Production-Ubuntu.md#set-up-nginx-server). - - -###### `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. - - **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 deleted file mode 100644 index 1f3ff9510..000000000 --- a/doc/install/Upgrade-Guide.md +++ /dev/null @@ -1,81 +0,0 @@ -# Mattermost Upgrade Guide - -### Upgrading Mattermost to Next Major Release - -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** - 2. Identify the next major build release of your Mattermost server from the list of [stable Mattermost releases](https://github.com/mattermost/platform/releases) - 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 (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.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` -2. Backup your data - 1. Back up your `config.json` file, which contains your system configuration. This will be used to restore your current settings after the new version is installed - 2. Backup your database using your organization's standard procedures for backing up MySQL or PostgreSQL - 3. If you're using local file storage, back up the location where files are stored -4. Decompress `mattermost.tar.gz` and use its contents to replace the current version of Mattermost on disk - 1. Run `tar -xvzf mattermost.tar.gz` -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. 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) - -The following instructions apply to updating installations of Mattermost v0.7-Beta to Mattermost 1.1. - -## GitLab Mattermost Upgrade Troubleshooting - -#### Upgrading GitLab Mattermost when GitLab upgrade skips versions - -Mattermost is designed to be upgraded sequentially through major version releases. If you skip versions when upgrading GitLab, you may find a `panic: The database schema version of 1.1.0 cannot be upgraded. You must not skip a version` error in your `/var/log/gitlab/mattermost/current` directory. If so: - -1. Run `platform -version` to check your version of Mattermost -2. If your version of the Mattermost binary doesn't match the version listed in the database error message, downgrade the version of the Mattermost binary you are using by [following the manual upgrade steps for Mattermost](https://github.com/mattermost/platform/blob/master/doc/install/Upgrade-Guide.md#upgrading-mattermost-to-next-major-release) and using the database schema version listed in the error messages for the version you select in Step 1) iv). -3. Once Mattermost is working again, you can use the same upgrade procedure to upgrade Mattermost version by version to your current GitLab version. After this is done, GitLab automation should continue to work for future upgrades, so long as you don't skip versions. - -| GitLab Version | Mattermost Version | -|----------------|---------------------| -| 8.1.x | v1.1.0 | -| 8.2.x | v1.2.1 | -| 8.3.x | v1.3.0 | - -## Upgrade Guide for Mattermost Beta Release - -#### Upgrading Mattermost in GitLab 8.0 to GitLab 8.1 with omnibus - -Mattermost 0.7.1-beta in GitLab 8.0 was a pre-release of Mattermost and Mattermost v1.1.1 in GitLab 8.1 was [updated significantly](https://github.com/mattermost/platform/blob/master/CHANGELOG.md#configjson-changes-from-v07-to-v10) to get to a stable, forwards-compatible platform for Mattermost. - -The Mattermost team didn't think it made sense for GitLab omnibus to attempt an automated re-configuration of Mattermost (since 0.7.1-beta was a pre-release) given the scale of change, so we're providing instructions for GitLab users who have customized their Mattermost deployments in 8.0 to move to 8.1: - -1. Follow the [Upgrading Mattermost v0.7.1-beta to v1.1.1 instructions](https://github.com/mattermost/platform/blob/master/doc/install/Upgrade-Guide.md#upgrading-mattermost-v071-beta-to-v111) below to identify the settings in Mattermost's `config.json` file that differ from defaults and need to be updated from GitLab 8.0 to 8.1 -2. Upgrade to GitLab 8.1 using omnibus, and allowing it overwrite `config.json` to the new Mattermost v1.1.1 format -3. Manually update `config.json` to new settings identified in Step 1 - -Optionally, you can use the new [System Console user interface](https://github.com/mattermost/platform/blob/master/doc/install/Configuration-Settings.md) to make changes to your new `config.json` file. - -#### Upgrading Mattermost v0.7.1-beta to v1.1.1 - -_Note: [Mattermost v1.1.1](https://github.com/mattermost/platform/releases/tag/v1.1.1) is a special release of Mattermost v1.1 that upgrades the database to Mattermost v1.1 from EITHER Mattermost v0.7 or Mattermost v1.0. The following instructions are for upgrading from Mattermost v0.7.1-beta to v1.1.1 and skipping the upgrade to Mattermost v1.0._ - -If you've manually changed Mattermost v0.7.1-beta configuration by updating the `config.json` file, you'll need to port those changes to Mattermost v1.1.1: - -1. Go to the `config.json` file that you manually updated and note any differences from the [default `config.json` file in Mattermost 0.7](https://github.com/mattermost/platform/blob/v0.7.0/config/config.json). - -2. For each setting that you changed, check [the changelog documentation](https://github.com/mattermost/platform/blob/master/CHANGELOG.md#configjson-changes-from-v07-to-v10) on whether the configuration setting has changed between v0.7 and v1.1.1 - -3. Update your new [`config.json` file in Mattermost v1.1](https://github.com/mattermost/platform/blob/v1.1.0/config/config.json), based on your preferences and the changelog documentation above - -Optionally, you can use the new [System Console user interface](https://github.com/mattermost/platform/blob/master/doc/install/Configuration-Settings.md) to make changes to your new `config.json` file. |