From 341d270c2d8b750556d9735a9a8edd8b6fab2530 Mon Sep 17 00:00:00 2001 From: Christopher Speller Date: Fri, 2 Oct 2015 14:48:50 -0400 Subject: Adding doc system to build. Updated docs, fixed links. --- doc/README.md | 37 +++-- doc/config/smtp-email-setup.md | 41 ------ doc/developer/Code-Contribution-Guidelines.md | 46 +++++++ doc/developer/Setup.md | 83 ++++++++++++ doc/developer/Style-Guide.md | 170 +++++++++++++++++++++++ doc/developer/code-contribution.md | 46 ------- doc/developer/style-guide.md | 170 ----------------------- doc/favicon.ico | 0 doc/help/enduser/markdown.md | 152 --------------------- doc/import/slack-import.md | 18 --- doc/install/Amazon-Elastic-Beanstalk.md | 27 ++++ doc/install/Docker-Single-Container.md | 117 ++++++++++++++++ doc/install/Production-Ubuntu.md | 186 ++++++++++++++++++++++++++ doc/install/Release-Numbering.md | 17 +++ doc/install/Requirements.md | 70 ++++++++++ doc/install/SMTP-Email-Setup.md | 41 ++++++ doc/install/aws-ebs-setup.md | 27 ---- doc/install/dev-setup.md | 83 ------------ doc/install/prod-ubuntu.md | 186 -------------------------- doc/install/release-numbering.md | 17 --- doc/install/requirements.md | 70 ---------- doc/install/single-container-install.md | 117 ---------------- doc/integrations/Single-Sign-On/Gitlab.md | 19 +++ doc/integrations/sso/gitlab-sso.md | 19 --- doc/integrations/webhook/incoming.md | 62 --------- doc/integrations/webhooks/Incoming.md | 62 +++++++++ doc/usage/Markdown.md | 152 +++++++++++++++++++++ doc/usage/Slack-Import.md | 18 +++ 28 files changed, 1024 insertions(+), 1029 deletions(-) delete mode 100644 doc/config/smtp-email-setup.md create mode 100644 doc/developer/Code-Contribution-Guidelines.md create mode 100644 doc/developer/Setup.md create mode 100644 doc/developer/Style-Guide.md delete mode 100644 doc/developer/code-contribution.md delete mode 100644 doc/developer/style-guide.md create mode 100644 doc/favicon.ico delete mode 100644 doc/help/enduser/markdown.md delete mode 100644 doc/import/slack-import.md create mode 100644 doc/install/Amazon-Elastic-Beanstalk.md create mode 100644 doc/install/Docker-Single-Container.md create mode 100644 doc/install/Production-Ubuntu.md create mode 100644 doc/install/Release-Numbering.md create mode 100644 doc/install/Requirements.md create mode 100644 doc/install/SMTP-Email-Setup.md delete mode 100644 doc/install/aws-ebs-setup.md delete mode 100644 doc/install/dev-setup.md delete mode 100644 doc/install/prod-ubuntu.md delete mode 100644 doc/install/release-numbering.md delete mode 100644 doc/install/requirements.md delete mode 100644 doc/install/single-container-install.md create mode 100644 doc/integrations/Single-Sign-On/Gitlab.md delete mode 100644 doc/integrations/sso/gitlab-sso.md delete mode 100644 doc/integrations/webhook/incoming.md create mode 100644 doc/integrations/webhooks/Incoming.md create mode 100644 doc/usage/Markdown.md create mode 100644 doc/usage/Slack-Import.md (limited to 'doc') diff --git a/doc/README.md b/doc/README.md index dc1591705..d711b5d53 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,31 +1,26 @@ # Mattermost Documentation -## General Information +## Installation -- [Mattermost Release Numbering Scheme](install/release-numbering.md) +- [AWS Elastic Beanstalk Setup](install/Amazon-Elastic-Beanstalk.md) +- [Docker Single Container Preview Setup](install/Docker-Single-Container.md) +- [Production Ubuntu Setup](install/Production-Ubuntu.md) +- [Mattermost Release Numbering Scheme](install/Release-Numbering.md) +- [Software and Hardware Requirements](install/Requirements.md) +- [SMTP Email Setup](install/SMTP-Email-Setup.md) -## Administrator Documentation +## Integrations -### Installation - -- [Software and Hardware Requirements](install/requirements.md) -- [Production Installation](install/prod-ubuntu.md) -- [Local Machine Setup ](install/single-container-install.md) -- [AWS Elastic Beanstalk Setup](install/aws-ebs-setup.md) -- [Developer Machine Setup](install/dev-setup.md) - -### Configuration - -- [GitLab SSO Configuration](integrations/sso/gitlab-sso.md) -- [SMTP Email Setup](config/smtp-email-setup.md) +- [GitLab SSO Configuration](integrations/Single-Sign-On/Gitlab.md) +- [Incoming Webhooks](integrations/webhooks/Incoming.md) ## Developer Documentation -- [Code Contribution Guidelines](developer/code-contribution.md) -- [Developer Machine Setup](install/dev-setup.md) -- [Mattermost Style Guide](developer/style-guide.md) +- [Code Contribution Guidelines](developer/Code-Contribution-Guidelines.md) +- [Developer Machine Setup](developer/Setup.md) +- [Mattermost Style Guide](developer/Style-Guide.md) -## End User Help +## Usage Help -- [Mattermost Markdown Formatting](help/enduser/markdown.md) -- [Slack Import](https://github.com/mattermost/platform/blob/master/doc/import/slack-import.md) +- [Slack Import](usage/Slack-Import.md) +- [Mattermost Markdown Formatting](usage/Markdown.md) diff --git a/doc/config/smtp-email-setup.md b/doc/config/smtp-email-setup.md deleted file mode 100644 index 86e2bb20e..000000000 --- a/doc/config/smtp-email-setup.md +++ /dev/null @@ -1,41 +0,0 @@ - -## SMTP Email Setup - -In some product evaluation setups email is intentionally bypassed using a `ByPassEmail=true` option. This option allows account creation and system operation without having to set up an email service (e.g. no email verification is required for account creation). This also means neither email notifications nor password reset by email are available. - -To enable email, turn this option off by setting `ByPassEmail=false` and configuring an SMTP email service as follows: - -1. **Set up an SMTP email sending service.** (If you already have credentials for a SMTP server you can skip this step.) - 1. [Setup Amazon Simple Email Service](https://console.aws.amazon.com/ses) - 2. From the `SMTP Settings` menu click `Create My SMTP Credentials` - 3. Copy the `Server Name`, `Port`, `SMTP Username`, and `SMTP Password` - 4. From the `Domains` menu setup and verify a new domain. It it also a good practice to enable `Generate DKIM Settings` for this domain. - 5. Choose an email address like `feedback@example.com` for Mattermost to send emails from. - 6. Test sending an email from `feedback@example.com` by clicking the `Send a Test Email` button and verify everything appears to be working correctly. -2. **Modify the Mattermost configuration file config.json or config_docker.json with the SMTP information.** - 1. If you're running Mattermost on Amazon Beanstalk you can shell into the instance with the following commands - 2. `ssh ec2-user@[domain for the docker instance]` - 3. `sudo gpasswd -a ec2-user docker` - 4. Retrieve the name of the container with `sudo docker ps` - 5. `sudo docker exec -ti container_name /bin/bash` -3. **Edit the config file `vi /config_docker.json` with the settings you captured from the step above.** - 1. See an example below and notice `ByPassEmail` has been set to `false` - ``` bash - "EmailSettings": { - "ByPassEmail" : false, - "SMTPUsername": "AKIADTOVBGERKLCBV", - "SMTPPassword": "jcuS8PuvcpGhpgHhlcpT1Mx42pnqMxQY", - "SMTPServer": "email-smtp.us-east-1.amazonaws.com:465", - "UseTLS": true, - "FeedbackEmail": "feedback@example.com", - "FeedbackName": "Feedback", - "ApplePushServer": "", - "ApplePushCertPublic": "", - "ApplePushCertPrivate": "" - } - ``` -4. **Restart Mattermost** - 1. Find the process id with `ps -A` and look for the process named `platform` - 2. Kill the process `kill pid` - 3. The service should restart automatically. Verify the Mattermost service is running with `ps -A` - 4. Current logged in users will not be affected, but upon logging out or session expiration users will be required to verify their email address. diff --git a/doc/developer/Code-Contribution-Guidelines.md b/doc/developer/Code-Contribution-Guidelines.md new file mode 100644 index 000000000..80676f107 --- /dev/null +++ b/doc/developer/Code-Contribution-Guidelines.md @@ -0,0 +1,46 @@ +# Code Contribution Guidelines + +Thank you for your interest in contributing to Mattermost. This guide provides an overview of important information for contributors to know. + +## Choose a Ticket + +1. Review the list of [Good First Contribution](https://mattermost.atlassian.net/issues/?filter=10206) tickets listed in Jira. + +2. These projects are intended to be a straight forward first pull requests from new contributors. +If you don't find something appropriate for your interests, please see the full list of tickets [Accepting Pull Requests](https://mattermost.atlassian.net/issues/?filter=10101). + +3. If you have any questions at all about a ticket, please post to the [Contributor Discussion section](http://forum.mattermost.org/) of the Mattermost forum, or email the [Mattermost Developer Mailing list](https://groups.google.com/a/mattermost.com/forum/#!forum/developer/join). + +## Install Mattermost and set up a Fork + +1. Follow [developer setup instructions](https://github.com/mattermost/platform/blob/master/doc/install/dev-setup.md) to install Mattermost. + +2. Create a branch with set to the ID of the ticket you're working on, for example ```PLT-394```, using command: + +``` +git checkout -b +``` + +## Programming and Testing + +1. Please review the [Mattermost Style Guide](Style-Guide.md) prior to making changes. + + To keep code clean and well structured, Mattermost uses ESLint to check that pull requests adhere to style guidelines for React. Code will need to follow Mattermost's React style guidelines in order to pass the automated build tests when a pull request is submitted. + +2. Please make sure to thoroughly test your change before submitting a pull request. + +## Submitting a Pull Request + +1. Please add yourself to the Mattermost [approved contributor list](https://docs.google.com/spreadsheets/d/1NTCeG-iL_VS9bFqtmHSfwETo5f-8MQ7oMDE5IUYJi_Y/pubhtml?gid=0&single=true) prior to submitting by completing the [contributor license agreement](http://www.mattermost.org/mattermost-contributor-agreement/). + +2. When you submit your pull request please include the Ticket ID at the beginning of your pull request comment, followed by a colon. + + For example, for a ticket ID `PLT-394` start your comment with: `PLT-394:`. See [previously closed pull requests](https://github.com/mattermost/platform/pulls?q=is%3Apr+is%3Aclosed) for examples. + +3. Once submitted, your pull request will be checked via an automated build process and will be reviewed by the Mattermost core team, who may either accept the PR or follow-up with feedback. + +4. If you've included your mailing address in Step 1, you'll be receiving a [Limited Edition Mattermost Mug](http://forum.mattermost.org/t/limited-edition-mattermost-mugs/143) as a thank you gift after your first pull request has been accepted. + + + + diff --git a/doc/developer/Setup.md b/doc/developer/Setup.md new file mode 100644 index 000000000..c63bde512 --- /dev/null +++ b/doc/developer/Setup.md @@ -0,0 +1,83 @@ +Developer Machine Setup +----------------------------- + +### Mac OS X ### + +1. Download and set up Docker Toolbox + 1. Follow the instructions at http://docs.docker.com/installation/mac/ + 2. Start a new docker host + `docker-machine create -d virtualbox dev` + 2. Get the IP address of your docker host + `docker-machine ip dev` + 3. Add a line to your /etc/hosts that goes ` dockerhost` + 4. Run `docker-machine env dev` and copy the export statements to your ~/.bash_profile +2. Download Go (version 1.4.2) from http://golang.org/dl/ +3. Set up your Go workspace + 1. `mkdir ~/go` + 2. Add the following to your ~/.bash_profile + `export GOPATH=$HOME/go` + `export PATH=$PATH:$GOPATH/bin` + 3. Reload your bash profile + `source ~/.bash_profile` +4. Install Node.js using Homebrew + 1. Download Homebrew from http://brew.sh/ + 2. `brew install node` +5. Install Compass + 1. Run `ruby -v` and check the ruby version is 1.8.7 or higher + 2. `sudo gem install compass` +6. Download Mattermost + `cd ~/go` + `mkdir -p src/github.com/mattermost` + `cd src/github.com/mattermost` + `git clone https://github.com/mattermost/platform.git` + `cd platform` +7. Run unit tests on Mattermost using `make test` to make sure the installation was successful +8. If tests passed, you can now run Mattermost using `make run` + +Any issues? Please let us know on our forums at: http://forum.mattermost.org + +### Ubuntu ### + +1. Download Docker + 1. Follow the instructions at https://docs.docker.com/installation/ubuntulinux/ or use the summary below: + `sudo apt-get update` + `sudo apt-get install wget` + `wget -qO- https://get.docker.com/ | sh` + `sudo usermod -aG docker ` + `sudo service docker start` + `newgrp docker` +2. Set up your dockerhost address + 1. Edit your /etc/hosts file to include the following line + `127.0.0.1 dockerhost` +3. Install build essentials + 1. `apt-get install build-essential` +4. Download Go (version 1.4.2) from http://golang.org/dl/ +5. Set up your Go workspace and add Go to the PATH + 1. `mkdir ~/go` + 2. Add the following to your ~/.bashrc + `export GOPATH=$HOME/go` + `export GOROOT=/usr/local/go` + `export PATH=$PATH:$GOROOT/bin` + 3. Reload your bashrc + `source ~/.bashrc` +6. Install Node.js + 1. Download the newest version of the Node.js sources from https://nodejs.org/download/ + 2. Extract the contents of the package and cd into the extracted files + 3. Compile and install Node.js + `./configure` + `make` + `make install` +7. Install Ruby and Compass + `apt-get install ruby` + `apt-get install ruby-dev` + `gem install compass` +8. Download Mattermost + `cd ~/go` + `mkdir -p src/github.com/mattermost` + `cd src/github.com/mattermost` + `git clone https://github.com/mattermost/platform.git` + `cd platform` +9. Run unit tests on Mattermost using `make test` to make sure the installation was successful +10. If tests passed, you can now run Mattermost using `make run` + +Any issues? Please let us know on our forums at: http://forum.mattermost.org diff --git a/doc/developer/Style-Guide.md b/doc/developer/Style-Guide.md new file mode 100644 index 000000000..a06f9e29b --- /dev/null +++ b/doc/developer/Style-Guide.md @@ -0,0 +1,170 @@ +# Mattermost Style Guide + +1. [Go](#go) +2. [Javascript](#javascript) +3. [React-JSX](#react-jsx) + + +## Go + +All go code must follow the golang official [Style Guide](https://golang.org/doc/effective_go.html) + +In addition all code must be run though the official go formatter tool [gofmt](https://golang.org/cmd/gofmt/) + + +## Javascript + +Part of the build process is running ESLint. ESLint is the final authority on all style issues. PRs will not be accepted unless there are no errors running ESLint. The ESLint configuration file can be found in: [web/react/.eslintrc](/web/react/.eslintrc) + +Instructions on how to use ESLint with your favourite editor can be found here: [http://eslint.org/docs/user-guide/integrations](http://eslint.org/docs/user-guide/integrations) + +You can run eslint using the makefile by using `make check` + +The following is a subset of what ESLint checks for. ESLint is always the authority. + +### Whitespace + +- Indentation is four spaces. +- Use a space before the leading brace. +- Use one space between the comma and the next argument in a bracketed list. No other space. +- Use whitespace to make code more readable. +- Do not use more than one newline to separate code blocks. +- Do not use a newline as the first line of a function + +```javascript +// Correct +function myFunction(parm1, parm2) { + stuff...; + + morestuff; +} + +// Incorrect +function myFunction ( parm1, parm2 ){ + stuff...; + + + morestuff; +} + +``` + +### Semicolons + +- You must use them always. + +```javascript +// Correct +let x = 1; + +// Incorrect +let x = 1 +``` + +### Variables + +- Declarations must always use var, let or const. +- Prefer let or const over var. +- camelCase for all variable names. + +```javascript +// Correct +let myVariable = 4; + +// OK +var myVariable = 4; + +// Incorrect +myVariable = 4; +var my_variable = 4; +``` + +### Blocks + +- Braces must be used on all blocks. +- Braces must start on the same line as the statement starting the block. +- Else and else if must be on the same line as the if block closing brace. + +```javascript +// Correct +if (something) { + stuff...; +} else if (otherthing) { + stuff...; +} + +// Incorrect +if (something) +{ + stuff...; +} +else +{ + stuff...; +} + +// Incorrect +if (something) stuff...; +if (something) + stuff...; + +``` + +### Strings + +- Use of template strings is preferred instead of concatenation. + +```javascript +// Correct +function getStr(stuff) { + return "This is the ${stuff} string"; +} + +// Incorrect +function wrongGetStr(stuff) { + return "This is the " + stuff + " string"; +} +``` + +## React-JSX + +Part of the build process is running ESLint. ESLint is the final authority on all style issues. PRs will not be accepted unless there are no errors running ESLint. The ESLint configuration file can be found in: [web/react/.eslintrc](/web/react/.eslintrc) + +Instructions on how to use ESLint with your favourite editor can be found here: [http://eslint.org/docs/user-guide/integrations](http://eslint.org/docs/user-guide/integrations) + +You can run eslint using the makefile by using `make check` + +The following is a subset of what ESLint checks for. ESLint is always the authority. + +### General + +- Include only one React component per file. +- Use class \ extends React.Component over React.createClass unless you need mixins +- Filenames should be the component name. + +### Alignment + +- Follow alignment styles shown below: +```xml +// Correct + + + + +// Correct + +``` + +### Naming + +- Property names use camelCase. +- React component names use CapitalCamelCase. +- Do not use an underscore for internal methods in a react component. + +```xml +// Correct + +``` diff --git a/doc/developer/code-contribution.md b/doc/developer/code-contribution.md deleted file mode 100644 index 51521be1b..000000000 --- a/doc/developer/code-contribution.md +++ /dev/null @@ -1,46 +0,0 @@ -# Code Contribution Guidelines - -Thank you for your interest in contributing to Mattermost. This guide provides an overview of important information for contributors to know. - -## Choose a Ticket - -1. Review the list of [Good First Contribution](https://mattermost.atlassian.net/issues/?filter=10206) tickets listed in Jira. - -2. These projects are intended to be a straight forward first pull requests from new contributors. -If you don't find something appropriate for your interests, please see the full list of tickets [Accepting Pull Requests](https://mattermost.atlassian.net/issues/?filter=10101). - -3. If you have any questions at all about a ticket, please post to the [Contributor Discussion section](http://forum.mattermost.org/) of the Mattermost forum, or email the [Mattermost Developer Mailing list](https://groups.google.com/a/mattermost.com/forum/#!forum/developer/join). - -## Install Mattermost and set up a Fork - -1. Follow [developer setup instructions](https://github.com/mattermost/platform/blob/master/doc/install/dev-setup.md) to install Mattermost. - -2. Create a branch with set to the ID of the ticket you're working on, for example ```PLT-394```, using command: - -``` -git checkout -b -``` - -## Programming and Testing - -1. Please review the [Mattermost Style Guide](style-guide.md) prior to making changes. - - To keep code clean and well structured, Mattermost uses ESLint to check that pull requests adhere to style guidelines for React. Code will need to follow Mattermost's React style guidelines in order to pass the automated build tests when a pull request is submitted. - -2. Please make sure to thoroughly test your change before submitting a pull request. - -## Submitting a Pull Request - -1. Please add yourself to the Mattermost [approved contributor list](https://docs.google.com/spreadsheets/d/1NTCeG-iL_VS9bFqtmHSfwETo5f-8MQ7oMDE5IUYJi_Y/pubhtml?gid=0&single=true) prior to submitting by completing the [contributor license agreement](http://www.mattermost.org/mattermost-contributor-agreement/). - -2. When you submit your pull request please include the Ticket ID at the beginning of your pull request comment, followed by a colon. - - For example, for a ticket ID `PLT-394` start your comment with: `PLT-394:`. See [previously closed pull requests](https://github.com/mattermost/platform/pulls?q=is%3Apr+is%3Aclosed) for examples. - -3. Once submitted, your pull request will be checked via an automated build process and will be reviewed by the Mattermost core team, who may either accept the PR or follow-up with feedback. - -4. If you've included your mailing address in Step 1, you'll be receiving a [Limited Edition Mattermost Mug](http://forum.mattermost.org/t/limited-edition-mattermost-mugs/143) as a thank you gift after your first pull request has been accepted. - - - - diff --git a/doc/developer/style-guide.md b/doc/developer/style-guide.md deleted file mode 100644 index a06f9e29b..000000000 --- a/doc/developer/style-guide.md +++ /dev/null @@ -1,170 +0,0 @@ -# Mattermost Style Guide - -1. [Go](#go) -2. [Javascript](#javascript) -3. [React-JSX](#react-jsx) - - -## Go - -All go code must follow the golang official [Style Guide](https://golang.org/doc/effective_go.html) - -In addition all code must be run though the official go formatter tool [gofmt](https://golang.org/cmd/gofmt/) - - -## Javascript - -Part of the build process is running ESLint. ESLint is the final authority on all style issues. PRs will not be accepted unless there are no errors running ESLint. The ESLint configuration file can be found in: [web/react/.eslintrc](/web/react/.eslintrc) - -Instructions on how to use ESLint with your favourite editor can be found here: [http://eslint.org/docs/user-guide/integrations](http://eslint.org/docs/user-guide/integrations) - -You can run eslint using the makefile by using `make check` - -The following is a subset of what ESLint checks for. ESLint is always the authority. - -### Whitespace - -- Indentation is four spaces. -- Use a space before the leading brace. -- Use one space between the comma and the next argument in a bracketed list. No other space. -- Use whitespace to make code more readable. -- Do not use more than one newline to separate code blocks. -- Do not use a newline as the first line of a function - -```javascript -// Correct -function myFunction(parm1, parm2) { - stuff...; - - morestuff; -} - -// Incorrect -function myFunction ( parm1, parm2 ){ - stuff...; - - - morestuff; -} - -``` - -### Semicolons - -- You must use them always. - -```javascript -// Correct -let x = 1; - -// Incorrect -let x = 1 -``` - -### Variables - -- Declarations must always use var, let or const. -- Prefer let or const over var. -- camelCase for all variable names. - -```javascript -// Correct -let myVariable = 4; - -// OK -var myVariable = 4; - -// Incorrect -myVariable = 4; -var my_variable = 4; -``` - -### Blocks - -- Braces must be used on all blocks. -- Braces must start on the same line as the statement starting the block. -- Else and else if must be on the same line as the if block closing brace. - -```javascript -// Correct -if (something) { - stuff...; -} else if (otherthing) { - stuff...; -} - -// Incorrect -if (something) -{ - stuff...; -} -else -{ - stuff...; -} - -// Incorrect -if (something) stuff...; -if (something) - stuff...; - -``` - -### Strings - -- Use of template strings is preferred instead of concatenation. - -```javascript -// Correct -function getStr(stuff) { - return "This is the ${stuff} string"; -} - -// Incorrect -function wrongGetStr(stuff) { - return "This is the " + stuff + " string"; -} -``` - -## React-JSX - -Part of the build process is running ESLint. ESLint is the final authority on all style issues. PRs will not be accepted unless there are no errors running ESLint. The ESLint configuration file can be found in: [web/react/.eslintrc](/web/react/.eslintrc) - -Instructions on how to use ESLint with your favourite editor can be found here: [http://eslint.org/docs/user-guide/integrations](http://eslint.org/docs/user-guide/integrations) - -You can run eslint using the makefile by using `make check` - -The following is a subset of what ESLint checks for. ESLint is always the authority. - -### General - -- Include only one React component per file. -- Use class \ extends React.Component over React.createClass unless you need mixins -- Filenames should be the component name. - -### Alignment - -- Follow alignment styles shown below: -```xml -// Correct - - - - -// Correct - -``` - -### Naming - -- Property names use camelCase. -- React component names use CapitalCamelCase. -- Do not use an underscore for internal methods in a react component. - -```xml -// Correct - -``` diff --git a/doc/favicon.ico b/doc/favicon.ico new file mode 100644 index 000000000..e69de29bb diff --git a/doc/help/enduser/markdown.md b/doc/help/enduser/markdown.md deleted file mode 100644 index 9e2342a0b..000000000 --- a/doc/help/enduser/markdown.md +++ /dev/null @@ -1,152 +0,0 @@ -# Markdown Help - -Markdown makes it easy to format messages. Type a message as you normally would, and use these rules to render it with special formatting. - -## Text Style: - -You can use either `_` or `*` around a word to make it italic. Use two to make it bold. - -* `_italics_` renders as _italics_ -* `**bold**` renders as **bold** -* `**_bold-italic_**` renders as **_bold-italics_** -* `~~strikethrough~~` renders as ~~strikethrough~~ - -## Code: - -Create a code block by indenting four spaces, or by placing ``` on the line above and below your code. - -Example: - - ``` - code block - ``` - -Renders as: -``` -code block -``` - -Create in-line monospaced font by surrounding it with back spaces. -``` -`monospace` -``` -Renders as: `monospace`. - -## Links: - -Create labeled links by putting the desired text in square brackets and the associated link in normal brackets. - -`[Check out Mattermost!](www.mattermost.com)` - -Renders as: [Check out Mattermost!](www.mattermost.com) - -## In-line Images - -Create in-line images using an `!` followed by the alt text in square brackets and the link in normal brackets. Add hover text by placing it in quotes after the link. -``` -![alt text](link "hover text") - -and - -[![Build Status](https://travis-ci.org/mattermost/platform.svg?branch=master)](https://travis-ci.org/mattermost/platform) [![Github](https://assets-cdn.github.com/favicon.ico)](https://github.com/mattermost/platform) -``` -Renders as: - -![alt text](link "hover text") - -and - -[![Build Status](https://travis-ci.org/mattermost/platform.svg?branch=master)](https://travis-ci.org/mattermost/platform) [![Github](https://assets-cdn.github.com/favicon.ico)](https://github.com/mattermost/platform) - -## Emojis - -Check out a full list of emojis [here](http://www.emoji-cheat-sheet.com/). - -``` -:smile: :+1: :sheep: -``` -Renders as: -:smile: :+1: :sheep: - -## Lines: - -Create a line by using three `*`, `_`, or `-`. - -`***` renders as: -*** - -## Block quotes: - -Create block quotes using `>`. - -`> block quotes` renders as: -> block quotes - -## Lists: - -Create a list by using `*` or `-` as bullets. Indent a bullet point by adding two spaces in front of it. -``` -* list item one -* list item two - * item two sub-point -``` -Renders as: -* list item one -* list item two - * item two sub-point - -Make it an ordered list by using numbers instead: -``` -1. Item one -2. Item two -``` -Renders as: -1. Item one -2. Item two - -## Tables: - -Create a table by placing a dashed line under the header row and separating the columns with a pipe `|`. (The columns don’t need to line up exactly for it to work). Choose how to align table columns by including colons `:` within the header row. -``` -| Left-Aligned  | Center Aligned  | Right Aligned | -| :------------ |:---------------:| -----:| -| Left column 1 | this text       |  $100 | -| Left column 2 | is              |   $10 | -| Left column 3 | centered        |    $1 | -``` - -Renders as: - -| Left-Aligned  | Center Aligned  | Right Aligned | -| :------------ |:---------------:| -----:| -| Left column 1 | this text       |  $100 | -| Left column 2 | is              |   $10 | -| Left column 3 | centered        |    $1 | - -## Headings: - -Make a heading by typing # and a space before your title. For smaller headings, use more #’s. -``` -# Large heading -## Smaller heading -### Even smaller heading -``` -Renders as: -# Large Heading -## Smaller Heading -### Even smaller heading - -Alternatively, for the large heading you can underline the text using `===`. For the smaller heading you can underline using `---` -``` -Large Heading -============= - -Smaller Heading --------------- -``` -Renders as: -Large Heading -============= - -Smaller Heading --------------- diff --git a/doc/import/slack-import.md b/doc/import/slack-import.md deleted file mode 100644 index c30de0567..000000000 --- a/doc/import/slack-import.md +++ /dev/null @@ -1,18 +0,0 @@ -#### Slack Import (Preview) - -*Note: As a SaaS service, Slack is able to change its export format quickly. If you encounter issues not mentioned in the documentation below, please let us know by [filing an issue](https://github.com/mattermost/platform/issues).* - -The Slack Import feature in Mattermost is in "Preview" and focus is on supporting migration of teams of less than 100 registered users. The feature can be accessed from by Team Administrators and Team Owners via the `Team Settings -> Import` menu option. - -Mattermost currently supports the processing of an "Export" file from Slack containing account information and public channel archives from a Slack team. - -- In the feature preview, emails and usernames from Slack are used to create new Mattermost accounts, connected to messages history in imported Slack channels. Users can activate these accounts and by going to the Password Reset screen in Mattermost to set new credentials. -- Once logged in, users will have access to previous Slack messages shared in public channels, now imported to Mattermost. - -Limitations: - -- Newly added markdown suppport in Slack's Posts 2.0 feature announced on September 28, 2015 is not yet supported. -- Slack does not export files or images your team has stored in Slack's database. Mattermost will provide links to the location of your assets in Slack's web UI. -- Slack does not export any content from private groups or direct messages that your team has stored in Slack's database. -- The Preview release of Slack Import does not offer pre-checks or roll-back and will not import Slack accounts with username or email address collisions with existing Mattermost accounts. Also, Slack channel names with underscores will not import. Also, mentions do not yet resolve as Mattermost usernames (still show Slack ID). - diff --git a/doc/install/Amazon-Elastic-Beanstalk.md b/doc/install/Amazon-Elastic-Beanstalk.md new file mode 100644 index 000000000..0416b67ea --- /dev/null +++ b/doc/install/Amazon-Elastic-Beanstalk.md @@ -0,0 +1,27 @@ + +## AWS Elastic Beanstalk Setup (Docker) + +1. Create a new Elastic Beanstalk Docker application using the [Dockerrun.aws.zip](https://github.com/mattermost/platform/raw/master/docker/1.0/Dockerrun.aws.zip) file provided. + 1. From the AWS console select Elastic Beanstalk. + 2. Select "Create New Application" from the top right. + 3. Name the application and press next. + 4. Select "Create a web server" environment. + 5. If asked, select create an IAM role and instance profile and press next. + 6. For predefined configuration select under Generic: Docker. For environment type select single instance. + 7. For application source, select upload your own and upload Dockerrun.aws.zip from [Dockerrun.aws.zip](https://github.com/mattermost/platform/raw/master/docker/1.0/Dockerrun.aws.zip). Everything else may be left at default. + 8. Select an environment name, this is how you will refer to your environment. Make sure the URL is available then press next. + 9. The options on the additional resources page may be left at default unless you wish to change them. Press Next. + 10. On the configuration details place. Select an instance type of t2.small or larger. + 11. You can set the configuration details as you please but they may be left at their defaults. When you are done press next. + 12. Environment tags my be left blank. Press next. + 13. You will be asked to review your information. Press Launch. + +4. Try it out! + 14. Wait for beanstalk to update the environment. + 15. Try it out by entering the domain of the form \*.elasticbeanstalk.com found at the top of the dashboard into your browser. You can also map your own domain if you wish. + + + ### (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). diff --git a/doc/install/Docker-Single-Container.md b/doc/install/Docker-Single-Container.md new file mode 100644 index 000000000..4b952cd71 --- /dev/null +++ b/doc/install/Docker-Single-Container.md @@ -0,0 +1,117 @@ +# 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. + +### 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 ` 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 + 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 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/Production-Ubuntu.md b/doc/install/Production-Ubuntu.md new file mode 100644 index 000000000..d2490062d --- /dev/null +++ b/doc/install/Production-Ubuntu.md @@ -0,0 +1,186 @@ +# Production Installation on Ubuntu 14.04 LTS + +## Install Ubuntu Server 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, and Database. +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.2+) + * ``` 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``` + +## 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.0.0/mattermost.tar.gz``` +1. Unzip the Mattermost Server by typing: + * ``` tar -xvzf mattermost.tar.gz``` +1. For the sake of making this guide simple we located the files at `/home/ubuntu/mattermost`. In the future we will give guidance for storing under `/opt`. +1. We have also elected to run the Mattermost Server as the `ubuntu` account for simplicity. We recommend settings up and running the service under a `mattermost` user account with limited permissions. +1. Create the storage directory for files. We assume you will have attached a large drive for storage of images and files. For this setup we will assume the directory is located at `/mattermost/data`. + * Create the directory by typing: + * ``` sudo mkdir -p /mattermost/data``` + * Set the ubuntu account as the directory owner by typing: + * ``` sudo chown -R ubuntu /mattermost``` +1. Configure Mattermost Server by editing the config.json file at /home/ubuntu/mattermost/config` + * ``` 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 Ubuntu 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://localhost: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. 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_session_timeout 5m; + ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2; + ssl_ciphers "HIGH:!aNULL:!MD5 or HIGH:!aNULL:!MD5:!3DES"; + ssl_prefer_server_ciphers on; + + # add to location / above + location / { + gzip off; + proxy_set_header X-Forwarded-Ssl on; +``` +## 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/Release-Numbering.md b/doc/install/Release-Numbering.md new file mode 100644 index 000000000..71374f7ef --- /dev/null +++ b/doc/install/Release-Numbering.md @@ -0,0 +1,17 @@ +### Mattermost 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 bugfix/security releases (e.g. 1.2.5, 1.2.6) diff --git a/doc/install/Requirements.md b/doc/install/Requirements.md new file mode 100644 index 000000000..1e0a12fb9 --- /dev/null +++ b/doc/install/Requirements.md @@ -0,0 +1,70 @@ +## Software Requirements + +### Web Client + +Supported Operating Systems and Browsers for the Mattermost Web Client include: + +- PC: Windows 7, Windows 8 (Chrome 43+, Firefox 38+, Internet Explorer 10+) +- Mac: OS 10 (Safari 7, Chrome 43+) +- Linux: Arch 4.0.0 (Chrome 43+) +- iPhone 4s and higher (Safari on iOS 8.3+, Chrome 43+) +- Android 5 and higher (Chrome 43+) + +### 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 across industries. + +### 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 new file mode 100644 index 000000000..86e2bb20e --- /dev/null +++ b/doc/install/SMTP-Email-Setup.md @@ -0,0 +1,41 @@ + +## SMTP Email Setup + +In some product evaluation setups email is intentionally bypassed using a `ByPassEmail=true` option. This option allows account creation and system operation without having to set up an email service (e.g. no email verification is required for account creation). This also means neither email notifications nor password reset by email are available. + +To enable email, turn this option off by setting `ByPassEmail=false` and configuring an SMTP email service as follows: + +1. **Set up an SMTP email sending service.** (If you already have credentials for a SMTP server you can skip this step.) + 1. [Setup Amazon Simple Email Service](https://console.aws.amazon.com/ses) + 2. From the `SMTP Settings` menu click `Create My SMTP Credentials` + 3. Copy the `Server Name`, `Port`, `SMTP Username`, and `SMTP Password` + 4. From the `Domains` menu setup and verify a new domain. It it also a good practice to enable `Generate DKIM Settings` for this domain. + 5. Choose an email address like `feedback@example.com` for Mattermost to send emails from. + 6. Test sending an email from `feedback@example.com` by clicking the `Send a Test Email` button and verify everything appears to be working correctly. +2. **Modify the Mattermost configuration file config.json or config_docker.json with the SMTP information.** + 1. If you're running Mattermost on Amazon Beanstalk you can shell into the instance with the following commands + 2. `ssh ec2-user@[domain for the docker instance]` + 3. `sudo gpasswd -a ec2-user docker` + 4. Retrieve the name of the container with `sudo docker ps` + 5. `sudo docker exec -ti container_name /bin/bash` +3. **Edit the config file `vi /config_docker.json` with the settings you captured from the step above.** + 1. See an example below and notice `ByPassEmail` has been set to `false` + ``` bash + "EmailSettings": { + "ByPassEmail" : false, + "SMTPUsername": "AKIADTOVBGERKLCBV", + "SMTPPassword": "jcuS8PuvcpGhpgHhlcpT1Mx42pnqMxQY", + "SMTPServer": "email-smtp.us-east-1.amazonaws.com:465", + "UseTLS": true, + "FeedbackEmail": "feedback@example.com", + "FeedbackName": "Feedback", + "ApplePushServer": "", + "ApplePushCertPublic": "", + "ApplePushCertPrivate": "" + } + ``` +4. **Restart Mattermost** + 1. Find the process id with `ps -A` and look for the process named `platform` + 2. Kill the process `kill pid` + 3. The service should restart automatically. Verify the Mattermost service is running with `ps -A` + 4. Current logged in users will not be affected, but upon logging out or session expiration users will be required to verify their email address. diff --git a/doc/install/aws-ebs-setup.md b/doc/install/aws-ebs-setup.md deleted file mode 100644 index e186fa9c1..000000000 --- a/doc/install/aws-ebs-setup.md +++ /dev/null @@ -1,27 +0,0 @@ - -## AWS Elastic Beanstalk Setup (Docker) - -1. Create a new Elastic Beanstalk Docker application using the [Dockerrun.aws.zip](/docker/0.7/Dockerrun.aws.zip) file provided. - 1. From the AWS console select Elastic Beanstalk. - 2. Select "Create New Application" from the top right. - 3. Name the application and press next. - 4. Select "Create a web server" environment. - 5. If asked, select create an IAM role and instance profile and press next. - 6. For predefined configuration select under Generic: Docker. For environment type select single instance. - 7. For application source, select upload your own and upload Dockerrun.aws.zip from [Dockerrun.aws.zip](/docker/0.7/Dockerrun.aws.zip). Everything else may be left at default. - 8. Select an environment name, this is how you will refer to your environment. Make sure the URL is available then press next. - 9. The options on the additional resources page may be left at default unless you wish to change them. Press Next. - 10. On the configuration details place. Select an instance type of t2.small or larger. - 11. You can set the configuration details as you please but they may be left at their defaults. When you are done press next. - 12. Environment tags my be left blank. Press next. - 13. You will be asked to review your information. Press Launch. - -4. Try it out! - 14. Wait for beanstalk to update the environment. - 15. Try it out by entering the domain of the form \*.elasticbeanstalk.com found at the top of the dashboard into your browser. You can also map your own domain if you wish. - - - ### (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](doc/config/smtp-email-setup.md). diff --git a/doc/install/dev-setup.md b/doc/install/dev-setup.md deleted file mode 100644 index c63bde512..000000000 --- a/doc/install/dev-setup.md +++ /dev/null @@ -1,83 +0,0 @@ -Developer Machine Setup ------------------------------ - -### Mac OS X ### - -1. Download and set up Docker Toolbox - 1. Follow the instructions at http://docs.docker.com/installation/mac/ - 2. Start a new docker host - `docker-machine create -d virtualbox dev` - 2. Get the IP address of your docker host - `docker-machine ip dev` - 3. Add a line to your /etc/hosts that goes ` dockerhost` - 4. Run `docker-machine env dev` and copy the export statements to your ~/.bash_profile -2. Download Go (version 1.4.2) from http://golang.org/dl/ -3. Set up your Go workspace - 1. `mkdir ~/go` - 2. Add the following to your ~/.bash_profile - `export GOPATH=$HOME/go` - `export PATH=$PATH:$GOPATH/bin` - 3. Reload your bash profile - `source ~/.bash_profile` -4. Install Node.js using Homebrew - 1. Download Homebrew from http://brew.sh/ - 2. `brew install node` -5. Install Compass - 1. Run `ruby -v` and check the ruby version is 1.8.7 or higher - 2. `sudo gem install compass` -6. Download Mattermost - `cd ~/go` - `mkdir -p src/github.com/mattermost` - `cd src/github.com/mattermost` - `git clone https://github.com/mattermost/platform.git` - `cd platform` -7. Run unit tests on Mattermost using `make test` to make sure the installation was successful -8. If tests passed, you can now run Mattermost using `make run` - -Any issues? Please let us know on our forums at: http://forum.mattermost.org - -### Ubuntu ### - -1. Download Docker - 1. Follow the instructions at https://docs.docker.com/installation/ubuntulinux/ or use the summary below: - `sudo apt-get update` - `sudo apt-get install wget` - `wget -qO- https://get.docker.com/ | sh` - `sudo usermod -aG docker ` - `sudo service docker start` - `newgrp docker` -2. Set up your dockerhost address - 1. Edit your /etc/hosts file to include the following line - `127.0.0.1 dockerhost` -3. Install build essentials - 1. `apt-get install build-essential` -4. Download Go (version 1.4.2) from http://golang.org/dl/ -5. Set up your Go workspace and add Go to the PATH - 1. `mkdir ~/go` - 2. Add the following to your ~/.bashrc - `export GOPATH=$HOME/go` - `export GOROOT=/usr/local/go` - `export PATH=$PATH:$GOROOT/bin` - 3. Reload your bashrc - `source ~/.bashrc` -6. Install Node.js - 1. Download the newest version of the Node.js sources from https://nodejs.org/download/ - 2. Extract the contents of the package and cd into the extracted files - 3. Compile and install Node.js - `./configure` - `make` - `make install` -7. Install Ruby and Compass - `apt-get install ruby` - `apt-get install ruby-dev` - `gem install compass` -8. Download Mattermost - `cd ~/go` - `mkdir -p src/github.com/mattermost` - `cd src/github.com/mattermost` - `git clone https://github.com/mattermost/platform.git` - `cd platform` -9. Run unit tests on Mattermost using `make test` to make sure the installation was successful -10. If tests passed, you can now run Mattermost using `make run` - -Any issues? Please let us know on our forums at: http://forum.mattermost.org diff --git a/doc/install/prod-ubuntu.md b/doc/install/prod-ubuntu.md deleted file mode 100644 index d2490062d..000000000 --- a/doc/install/prod-ubuntu.md +++ /dev/null @@ -1,186 +0,0 @@ -# Production Installation on Ubuntu 14.04 LTS - -## Install Ubuntu Server 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, and Database. -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.2+) - * ``` 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``` - -## 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.0.0/mattermost.tar.gz``` -1. Unzip the Mattermost Server by typing: - * ``` tar -xvzf mattermost.tar.gz``` -1. For the sake of making this guide simple we located the files at `/home/ubuntu/mattermost`. In the future we will give guidance for storing under `/opt`. -1. We have also elected to run the Mattermost Server as the `ubuntu` account for simplicity. We recommend settings up and running the service under a `mattermost` user account with limited permissions. -1. Create the storage directory for files. We assume you will have attached a large drive for storage of images and files. For this setup we will assume the directory is located at `/mattermost/data`. - * Create the directory by typing: - * ``` sudo mkdir -p /mattermost/data``` - * Set the ubuntu account as the directory owner by typing: - * ``` sudo chown -R ubuntu /mattermost``` -1. Configure Mattermost Server by editing the config.json file at /home/ubuntu/mattermost/config` - * ``` 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 Ubuntu 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://localhost: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. 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_session_timeout 5m; - ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2; - ssl_ciphers "HIGH:!aNULL:!MD5 or HIGH:!aNULL:!MD5:!3DES"; - ssl_prefer_server_ciphers on; - - # add to location / above - location / { - gzip off; - proxy_set_header X-Forwarded-Ssl on; -``` -## 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/release-numbering.md b/doc/install/release-numbering.md deleted file mode 100644 index 71374f7ef..000000000 --- a/doc/install/release-numbering.md +++ /dev/null @@ -1,17 +0,0 @@ -### Mattermost 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 bugfix/security releases (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 1e0a12fb9..000000000 --- a/doc/install/requirements.md +++ /dev/null @@ -1,70 +0,0 @@ -## Software Requirements - -### Web Client - -Supported Operating Systems and Browsers for the Mattermost Web Client include: - -- PC: Windows 7, Windows 8 (Chrome 43+, Firefox 38+, Internet Explorer 10+) -- Mac: OS 10 (Safari 7, Chrome 43+) -- Linux: Arch 4.0.0 (Chrome 43+) -- iPhone 4s and higher (Safari on iOS 8.3+, Chrome 43+) -- Android 5 and higher (Chrome 43+) - -### 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 across industries. - -### 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/single-container-install.md b/doc/install/single-container-install.md deleted file mode 100644 index 304467678..000000000 --- a/doc/install/single-container-install.md +++ /dev/null @@ -1,117 +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. - -### 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 ` 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 - 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 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/config.json](config/config.json) or [docker/0.6/config_docker.json](docker/0.6/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](/doc/config/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/integrations/Single-Sign-On/Gitlab.md b/doc/integrations/Single-Sign-On/Gitlab.md new file mode 100644 index 000000000..6110db504 --- /dev/null +++ b/doc/integrations/Single-Sign-On/Gitlab.md @@ -0,0 +1,19 @@ +## Configuring GitLab Single-Sign-On + +The following steps can be used to configure Mattermost to use GitLab as a single-sign-on (SSO) service for team creation, account creation and sign-in. + +1. Login to your GitLab account and go to the Applications section either in Profile Settings or Admin Area. +2. Add a new application called "Mattermost" with the following as Redirect URIs: + * `/login/gitlab/complete` (example: http://localhost:8065/login/gitlab/complete) + * `/signup/gitlab/complete` + +3. Submit the application and copy the given _Id_ and _Secret_ into the appropriate _SSOSettings_ fields in config/config.json + +4. Also in config/config.json, set _Allow_ to `true` for the _gitlab_ section, leave _Scope_ blank and use the following for the endpoints: + * _AuthEndpoint_: `/oauth/authorize` (example http://localhost:3000/oauth/authorize) + * _TokenEndpoint_: `/oauth/token` + * _UserApiEndpoint_: `/api/v3/user` + +6. (Optional) If you would like to force all users to sign-up with GitLab only, in the _ServiceSettings_ section of config/config.json please set _DisableEmailSignUp_ to `true`. + +7. Restart your Mattermost server to see the changes take effect. diff --git a/doc/integrations/sso/gitlab-sso.md b/doc/integrations/sso/gitlab-sso.md deleted file mode 100644 index 6110db504..000000000 --- a/doc/integrations/sso/gitlab-sso.md +++ /dev/null @@ -1,19 +0,0 @@ -## Configuring GitLab Single-Sign-On - -The following steps can be used to configure Mattermost to use GitLab as a single-sign-on (SSO) service for team creation, account creation and sign-in. - -1. Login to your GitLab account and go to the Applications section either in Profile Settings or Admin Area. -2. Add a new application called "Mattermost" with the following as Redirect URIs: - * `/login/gitlab/complete` (example: http://localhost:8065/login/gitlab/complete) - * `/signup/gitlab/complete` - -3. Submit the application and copy the given _Id_ and _Secret_ into the appropriate _SSOSettings_ fields in config/config.json - -4. Also in config/config.json, set _Allow_ to `true` for the _gitlab_ section, leave _Scope_ blank and use the following for the endpoints: - * _AuthEndpoint_: `/oauth/authorize` (example http://localhost:3000/oauth/authorize) - * _TokenEndpoint_: `/oauth/token` - * _UserApiEndpoint_: `/api/v3/user` - -6. (Optional) If you would like to force all users to sign-up with GitLab only, in the _ServiceSettings_ section of config/config.json please set _DisableEmailSignUp_ to `true`. - -7. Restart your Mattermost server to see the changes take effect. diff --git a/doc/integrations/webhook/incoming.md b/doc/integrations/webhook/incoming.md deleted file mode 100644 index e391cba92..000000000 --- a/doc/integrations/webhook/incoming.md +++ /dev/null @@ -1,62 +0,0 @@ -# Incoming Webhooks - -With incoming webhooks practically any external source - once given a URL by you - can post a message to any channel you have access to. This is done through a HTTP POST request with a simple JSON payload. The payload can contain some text, and some simple options to allow the external source to customize the post. - -## Creating the Webhook URL - -To get the incoming webhook URL - where all the HTTP requests will be sent - follow these steps: - -1. Login to your Mattermost account. -2. Open the menu by clicking near your profile picture in the top-left and open Account Settings. -3. Go to the Integrations tab and click the 'Edit' button next to 'Incoming Webhooks'. -4. Use the selector to choose a channel and click the 'Add' button to create the webhook. -5. Your webhook URL will be displayed below in the 'Existing incoming webhooks' section. - - -## Posting a Message - -You can send the message by including a JSON string as the `payload` parameter in a HTTP POST request. -``` -payload={"text": "Hello, this is some text."} -``` - -In addition, if `Content-Type` is specified as `application/json` in the headers of the HTTP request then the body of the request can be direct JSON. -``` -{"text": "Hello, this is some text."} -``` - -It is also possible to post richly formatted messages using [Markdown](../../help/enduser/markdown.md). -``` -payload={"text": "# A Header\nThe _text_ below **the** header."} -``` - -Just like regular posts, the text will be limited to 4000 characters at maximum. - -## Adding Links - -In addition to including links in the standard Markdown format, links can also be specified by enclosing the URL in `<>` brackets -``` -payload={"text": ""} -``` - -They can also include a `|` character to specify some clickable text. -``` -payload={"text": "Click for a link."} -``` - -## Channel Override - -You can use a single webhook URL to post messages to different channels by overriding the channel. You can do this by adding the channel name - as it is seen in the channel URL - to the request payload. -``` -payload={"channel": "off-topic", "text": "Hello, this is some text."} -``` - -## Finishing up - -Combining everything above, here is an example message made using a curl command: - -``` -curl -i -X POST 'payload={"channel": "off-topic", "text": "Hello, this is some text."}' http://yourmattermost.com/hooks/xxxxxxxxxxxxxxxxxxxxxxxxxx -``` - -A post with that text will be made to the Off-Topic channel. diff --git a/doc/integrations/webhooks/Incoming.md b/doc/integrations/webhooks/Incoming.md new file mode 100644 index 000000000..6e25f182e --- /dev/null +++ b/doc/integrations/webhooks/Incoming.md @@ -0,0 +1,62 @@ +# Incoming Webhooks + +With incoming webhooks practically any external source - once given a URL by you - can post a message to any channel you have access to. This is done through a HTTP POST request with a simple JSON payload. The payload can contain some text, and some simple options to allow the external source to customize the post. + +## Creating the Webhook URL + +To get the incoming webhook URL - where all the HTTP requests will be sent - follow these steps: + +1. Login to your Mattermost account. +2. Open the menu by clicking near your profile picture in the top-left and open Account Settings. +3. Go to the Integrations tab and click the 'Edit' button next to 'Incoming Webhooks'. +4. Use the selector to choose a channel and click the 'Add' button to create the webhook. +5. Your webhook URL will be displayed below in the 'Existing incoming webhooks' section. + + +## Posting a Message + +You can send the message by including a JSON string as the `payload` parameter in a HTTP POST request. +``` +payload={"text": "Hello, this is some text."} +``` + +In addition, if `Content-Type` is specified as `application/json` in the headers of the HTTP request then the body of the request can be direct JSON. +``` +{"text": "Hello, this is some text."} +``` + +It is also possible to post richly formatted messages using [Markdown](../../usage/Markdown.md). +``` +payload={"text": "# A Header\nThe _text_ below **the** header."} +``` + +Just like regular posts, the text will be limited to 4000 characters at maximum. + +## Adding Links + +In addition to including links in the standard Markdown format, links can also be specified by enclosing the URL in `<>` brackets +``` +payload={"text": ""} +``` + +They can also include a `|` character to specify some clickable text. +``` +payload={"text": "Click for a link."} +``` + +## Channel Override + +You can use a single webhook URL to post messages to different channels by overriding the channel. You can do this by adding the channel name - as it is seen in the channel URL - to the request payload. +``` +payload={"channel": "off-topic", "text": "Hello, this is some text."} +``` + +## Finishing up + +Combining everything above, here is an example message made using a curl command: + +``` +curl -i -X POST 'payload={"channel": "off-topic", "text": "Hello, this is some text."}' http://yourmattermost.com/hooks/xxxxxxxxxxxxxxxxxxxxxxxxxx +``` + +A post with that text will be made to the Off-Topic channel. diff --git a/doc/usage/Markdown.md b/doc/usage/Markdown.md new file mode 100644 index 000000000..9e2342a0b --- /dev/null +++ b/doc/usage/Markdown.md @@ -0,0 +1,152 @@ +# Markdown Help + +Markdown makes it easy to format messages. Type a message as you normally would, and use these rules to render it with special formatting. + +## Text Style: + +You can use either `_` or `*` around a word to make it italic. Use two to make it bold. + +* `_italics_` renders as _italics_ +* `**bold**` renders as **bold** +* `**_bold-italic_**` renders as **_bold-italics_** +* `~~strikethrough~~` renders as ~~strikethrough~~ + +## Code: + +Create a code block by indenting four spaces, or by placing ``` on the line above and below your code. + +Example: + + ``` + code block + ``` + +Renders as: +``` +code block +``` + +Create in-line monospaced font by surrounding it with back spaces. +``` +`monospace` +``` +Renders as: `monospace`. + +## Links: + +Create labeled links by putting the desired text in square brackets and the associated link in normal brackets. + +`[Check out Mattermost!](www.mattermost.com)` + +Renders as: [Check out Mattermost!](www.mattermost.com) + +## In-line Images + +Create in-line images using an `!` followed by the alt text in square brackets and the link in normal brackets. Add hover text by placing it in quotes after the link. +``` +![alt text](link "hover text") + +and + +[![Build Status](https://travis-ci.org/mattermost/platform.svg?branch=master)](https://travis-ci.org/mattermost/platform) [![Github](https://assets-cdn.github.com/favicon.ico)](https://github.com/mattermost/platform) +``` +Renders as: + +![alt text](link "hover text") + +and + +[![Build Status](https://travis-ci.org/mattermost/platform.svg?branch=master)](https://travis-ci.org/mattermost/platform) [![Github](https://assets-cdn.github.com/favicon.ico)](https://github.com/mattermost/platform) + +## Emojis + +Check out a full list of emojis [here](http://www.emoji-cheat-sheet.com/). + +``` +:smile: :+1: :sheep: +``` +Renders as: +:smile: :+1: :sheep: + +## Lines: + +Create a line by using three `*`, `_`, or `-`. + +`***` renders as: +*** + +## Block quotes: + +Create block quotes using `>`. + +`> block quotes` renders as: +> block quotes + +## Lists: + +Create a list by using `*` or `-` as bullets. Indent a bullet point by adding two spaces in front of it. +``` +* list item one +* list item two + * item two sub-point +``` +Renders as: +* list item one +* list item two + * item two sub-point + +Make it an ordered list by using numbers instead: +``` +1. Item one +2. Item two +``` +Renders as: +1. Item one +2. Item two + +## Tables: + +Create a table by placing a dashed line under the header row and separating the columns with a pipe `|`. (The columns don’t need to line up exactly for it to work). Choose how to align table columns by including colons `:` within the header row. +``` +| Left-Aligned  | Center Aligned  | Right Aligned | +| :------------ |:---------------:| -----:| +| Left column 1 | this text       |  $100 | +| Left column 2 | is              |   $10 | +| Left column 3 | centered        |    $1 | +``` + +Renders as: + +| Left-Aligned  | Center Aligned  | Right Aligned | +| :------------ |:---------------:| -----:| +| Left column 1 | this text       |  $100 | +| Left column 2 | is              |   $10 | +| Left column 3 | centered        |    $1 | + +## Headings: + +Make a heading by typing # and a space before your title. For smaller headings, use more #’s. +``` +# Large heading +## Smaller heading +### Even smaller heading +``` +Renders as: +# Large Heading +## Smaller Heading +### Even smaller heading + +Alternatively, for the large heading you can underline the text using `===`. For the smaller heading you can underline using `---` +``` +Large Heading +============= + +Smaller Heading +-------------- +``` +Renders as: +Large Heading +============= + +Smaller Heading +-------------- diff --git a/doc/usage/Slack-Import.md b/doc/usage/Slack-Import.md new file mode 100644 index 000000000..c30de0567 --- /dev/null +++ b/doc/usage/Slack-Import.md @@ -0,0 +1,18 @@ +#### Slack Import (Preview) + +*Note: As a SaaS service, Slack is able to change its export format quickly. If you encounter issues not mentioned in the documentation below, please let us know by [filing an issue](https://github.com/mattermost/platform/issues).* + +The Slack Import feature in Mattermost is in "Preview" and focus is on supporting migration of teams of less than 100 registered users. The feature can be accessed from by Team Administrators and Team Owners via the `Team Settings -> Import` menu option. + +Mattermost currently supports the processing of an "Export" file from Slack containing account information and public channel archives from a Slack team. + +- In the feature preview, emails and usernames from Slack are used to create new Mattermost accounts, connected to messages history in imported Slack channels. Users can activate these accounts and by going to the Password Reset screen in Mattermost to set new credentials. +- Once logged in, users will have access to previous Slack messages shared in public channels, now imported to Mattermost. + +Limitations: + +- Newly added markdown suppport in Slack's Posts 2.0 feature announced on September 28, 2015 is not yet supported. +- Slack does not export files or images your team has stored in Slack's database. Mattermost will provide links to the location of your assets in Slack's web UI. +- Slack does not export any content from private groups or direct messages that your team has stored in Slack's database. +- The Preview release of Slack Import does not offer pre-checks or roll-back and will not import Slack accounts with username or email address collisions with existing Mattermost accounts. Also, Slack channel names with underscores will not import. Also, mentions do not yet resolve as Mattermost usernames (still show Slack ID). + -- cgit v1.2.3-1-g7c22