diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.md | 2 | ||||
| -rw-r--r-- | doc/developer/API-Web-Service.md (renamed from doc/api/Overview.md) | 6 | ||||
| -rw-r--r-- | doc/developer/API.md | 12 | ||||
| -rw-r--r-- | doc/developer/Code-Contribution-Guidelines.md | 45 | ||||
| -rw-r--r-- | doc/help/Search.md | 6 | ||||
| -rw-r--r-- | doc/install/Administration.md | 19 | ||||
| -rw-r--r-- | doc/install/Amazon-Elastic-Beanstalk.md | 45 | ||||
| -rw-r--r-- | doc/install/Production-Debian.md | 302 | ||||
| -rw-r--r-- | doc/install/Production-Ubuntu.md | 11 | ||||
| -rw-r--r-- | doc/install/Requirements.md | 21 | ||||
| -rw-r--r-- | doc/install/SMTP-Email-Setup.md | 12 | ||||
| -rw-r--r-- | doc/install/Troubleshooting.md | 19 | ||||
| -rw-r--r-- | doc/install/Upgrade-Guide.md | 21 | ||||
| -rw-r--r-- | doc/integrations/Single-Sign-On/Gitlab.md | 4 | ||||
| -rw-r--r-- | doc/integrations/webhooks/Incoming-Webhooks.md | 44 | ||||
| -rw-r--r-- | doc/integrations/webhooks/Outgoing-Webhooks.md | 120 | ||||
| -rw-r--r-- | doc/process/documentation-guidelines.md | 185 | ||||
| -rw-r--r-- | doc/process/release-process.md | 99 |
18 files changed, 860 insertions, 113 deletions
diff --git a/doc/README.md b/doc/README.md index ccb702a5d..1b9cc759d 100644 --- a/doc/README.md +++ b/doc/README.md @@ -27,7 +27,7 @@ Set up Mattermost in your data center - [Code Contribution Guidelines](developer/Code-Contribution-Guidelines.md) - [Developer Machine Setup](developer/Setup.md) - [Mattermost Style Guide](developer/Style-Guide.md) -- [API Overview](api/Overview.md) +- [API Overview](developer/API.md) - [Incoming Webhooks](integrations/webhooks/Incoming-Webhooks.md) ## Help diff --git a/doc/api/Overview.md b/doc/developer/API-Web-Service.md index 0a407b1e9..53ebc869c 100644 --- a/doc/api/Overview.md +++ b/doc/developer/API-Web-Service.md @@ -1,6 +1,8 @@ -# API Overview +# Mattermost Web Service API -This provides a basic overview of the Mattermost API. All examples assume there is a Mattermost instance running at http://localhost:8065. +This provides a basic overview of the Mattermost Web Service API. Drivers interfacing with this API are available in different languages. Current documentation focuses on the transport layer for the API and functional documentation will be developed next. + +All examples assume there is a Mattermost instance running at http://localhost:8065. ## Schema diff --git a/doc/developer/API.md b/doc/developer/API.md index 6327f1173..4c4b2f04e 100644 --- a/doc/developer/API.md +++ b/doc/developer/API.md @@ -2,7 +2,7 @@ Mattermost APIs let you integrate your favorite tools and services withing your Mattermost experience. -## Slack-compatible integration support +## Slack-compatible Webhooks To offer an alternative to propreitary SaaS services, Mattermost focuses on being "Slack-compatible, but not Slack limited". That means providing support for developers of Slack applications to easily extend their apps to Mattermost, as well as support and capabilities beyond what Slack offers. @@ -12,19 +12,19 @@ Incoming webhooks allow external applications to post messages into Mattermost c In addition to supporting Slack's incoming webhook formatting, Mattermost webhooks offer full support of industry-standard markdown formatting, including headings, tables and in-line images. -### Outgoing Webhooks (coming in Mattermost v1.2) +### [Outgoing Webhooks (in Mattermost v1.2)](https://github.com/mattermost/platform/blob/master/doc/integrations/webhooks/Outgoing-Webhooks.md) Outgoing webhooks allow external applications to receive webhook events from events happening within Mattermost channels and private groups via JSON payloads via HTTP POST requests sent to incoming webhook URLs defined by your applications. Over time, Mattermost outgoing webhooks will support not only Slack applications using a compatible format, but also offer optional events and triggers beyond Slack's feature set. -## Mattermost Drivers +## Mattermost Web Service API -Mattermost is written in Golang and React and designed as a self-hosted system, which differs from Slack's technical platform and focus on SaaS. Therefore the Mattermost drivers will differ from Slack's interfaces. +Mattermost offers a Web Service API accessible by Mattermost Drivers, listed below. Initial documentation on the [transport layer for the web service is available](API-Web-Service.md) and functional documentation is under development. -Another key difference is that as an open source project, you are welcome to access and use Mattermost's APIs on your installations the same way the core team would use them for buildling new features. +## Mattermost Drivers -While detailed documentation of the interfaces is pending, if you want to build deep integrations with Mattermost there are two drivers at the heart of the system: +Mattermost drivers offer access to the Mattermost web service API in different languages and frameworks. ### [ReactJS Javascript Driver](https://github.com/mattermost/platform/blob/master/web/react/utils/client.jsx) diff --git a/doc/developer/Code-Contribution-Guidelines.md b/doc/developer/Code-Contribution-Guidelines.md index 48bbf2491..18be4aa0b 100644 --- a/doc/developer/Code-Contribution-Guidelines.md +++ b/doc/developer/Code-Contribution-Guidelines.md @@ -1,48 +1,5 @@ # 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/developer/Setup.md) to install Mattermost. - -2. Create a branch with <branch name> set to the ID of the ticket you're working on, for example ```PLT-394```, using command: - -``` -git checkout -b <branch name> -``` - -## 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. - - Please review the ["Fast, Obvious, Forgiving" experience design principles](http://www.mattermost.org/design-principles/) for Mattermost and check that your feature meets the criteria. Also, for any changes to user interface or help text, please read the changes out loud, as a quick and easy way to catch any inconsitencies. - - -## Submitting a Pull Request - -1. Please add yourself to the Mattermost [approved contributor list](https://docs.google.com/spreadsheets/d/1NTCeG-iL_VS9bFqtmHSfwETo5f-8MQ7oMDE5IUYJi_Y/pubhtml?gid=0&single=true) prior to submitting by completing the [contributor license agreement](http://www.mattermost.org/mattermost-contributor-agreement/). - -2. When you submit your pull request please make it against `master` and include the Ticket ID at the beginning of your pull request comment, followed by a colon. - - For example, for a ticket ID `PLT-394` start your comment with: `PLT-394:`. See [previously closed pull requests](https://github.com/mattermost/platform/pulls?q=is%3Apr+is%3Aclosed) for examples. - -3. Once submitted, your pull request will be checked via an automated build process and will be reviewed by at least two members of the Mattermost core team, who may either accept the PR or follow-up with feedback. It would then get merged into `master` for the next release. - -4. If you've included your mailing address in Step 1, you'll be receiving a [Limited Edition Mattermost Mug](http://forum.mattermost.org/t/limited-edition-mattermost-mugs/143) as a thank you gift after your first pull request has been accepted. - - +Please see [CONTRIBUTING.md](https://github.com/mattermost/platform/blob/master/CONTRIBUTING.md) diff --git a/doc/help/Search.md b/doc/help/Search.md index f36e079bd..02ecf7d40 100644 --- a/doc/help/Search.md +++ b/doc/help/Search.md @@ -8,4 +8,8 @@ Some things to know about search: - You can use quotes to return search results for exact terms, like `"Mattermost website"` will only return messages containing the entire phrase `"Mattermost website"` and not return messages with only `Mattermost` or `website` - You can use the `*` character for wildcard searches that match within words. For example: Searching for `rea*` brings back messages containing `reach`, `reason` and other words starting with `rea`. -Search in Mattermost uses the full text search features in MySQL and Postgres databases. Special cases that are not supported in default full text search, such as searching for IP addresses like `10.100.200.101`, can be added in future as the search feature evolves. +#### Limitations + +- Search in Mattermost uses the full text search features included in either a MySQL or Postgres database, which has some limitations + - Special cases that are not supported in default full text search, such as searching for IP addresses like `10.100.200.101`, can be added in future as the search feature evolves + - Searches with fewer than three characters will return no results, so for searching in Chinese try adding * to the end of queries diff --git a/doc/install/Administration.md b/doc/install/Administration.md new file mode 100644 index 000000000..ee996088c --- /dev/null +++ b/doc/install/Administration.md @@ -0,0 +1,19 @@ +# 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. diff --git a/doc/install/Amazon-Elastic-Beanstalk.md b/doc/install/Amazon-Elastic-Beanstalk.md index 0416b67ea..8738ab3ac 100644 --- a/doc/install/Amazon-Elastic-Beanstalk.md +++ b/doc/install/Amazon-Elastic-Beanstalk.md @@ -1,27 +1,26 @@ ## 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](https://github.com/mattermost/platform/raw/master/docker/1.1/Dockerrun.aws.zip). -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. +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](https://github.com/mattermost/platform/raw/master/docker/1.1/Dockerrun.aws.zip) 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! - To see the product's full functionality, [enabling SMTP email is recommended](SMTP-Email-Setup.md). +### (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). diff --git a/doc/install/Production-Debian.md b/doc/install/Production-Debian.md new file mode 100644 index 000000000..e97f3188b --- /dev/null +++ b/doc/install/Production-Debian.md @@ -0,0 +1,302 @@ +# (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. 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``` + +## 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.1.0/mattermost.tar.gz``` +1. Install Mattermost under /opt + * ``` cd /opt``` + * 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 /opt/mattermost/data``` +1. Create a system user and group called mattermost that will run this service + * ``` useradd -r mattermost -U``` + * Set the mattermost account as the directory owner by typing: + * ``` sudo chown -R mattermost:mattermost /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 + * ``` 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://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/mattermost/cert/mattermost.crt; + ssl_certificate_key /home/mattermost/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/Production-Ubuntu.md b/doc/install/Production-Ubuntu.md index 836af3995..2e02cca38 100644 --- a/doc/install/Production-Ubuntu.md +++ b/doc/install/Production-Ubuntu.md @@ -119,7 +119,7 @@ exec bin/platform ## 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. +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``` @@ -133,8 +133,8 @@ exec bin/platform 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 - * +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; @@ -149,9 +149,10 @@ exec bin/platform 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 SSLv3 TLSv1 TLSv1.1 TLSv1.2; - ssl_ciphers "HIGH:!aNULL:!MD5 or HIGH:!aNULL:!MD5:!3DES"; + ssl_protocols TLSv1 TLSv1.1 TLSv1.2; + ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH'; ssl_prefer_server_ciphers on; # add to location / above diff --git a/doc/install/Requirements.md b/doc/install/Requirements.md index 1e0a12fb9..61fa8e7be 100644 --- a/doc/install/Requirements.md +++ b/doc/install/Requirements.md @@ -10,6 +10,27 @@ Supported Operating Systems and Browsers for the Mattermost Web Client include: - iPhone 4s and higher (Safari on iOS 8.3+, 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: diff --git a/doc/install/SMTP-Email-Setup.md b/doc/install/SMTP-Email-Setup.md index bb57d95ba..7d9beae89 100644 --- a/doc/install/SMTP-Email-Setup.md +++ b/doc/install/SMTP-Email-Setup.md @@ -52,10 +52,18 @@ To enable email, configure an SMTP email service as follows: * Set **Connection Security** to **(empty)** ##### Gmail -* Information needed +* 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 -* Information needed +* 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** diff --git a/doc/install/Troubleshooting.md b/doc/install/Troubleshooting.md index 46efc61fa..7166f9978 100644 --- a/doc/install/Troubleshooting.md +++ b/doc/install/Troubleshooting.md @@ -8,10 +8,23 @@ #### Common Issues -##### Error message in logs when attempting to sign-up: `x509: certificate signed by unknown authority` - - This error may appear when attempt to use a self-signed certificate to setup SSL, which is not yet supported by Mattermost. You can resolve this issue by setting up a load balancer like Ngnix. A ticket exists to [add support for self-signed certificates in future](x509: certificate signed by unknown authority). - ##### 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. +#### 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. You + - **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. diff --git a/doc/install/Upgrade-Guide.md b/doc/install/Upgrade-Guide.md index cecd45353..fc3a0711f 100644 --- a/doc/install/Upgrade-Guide.md +++ b/doc/install/Upgrade-Guide.md @@ -1,10 +1,23 @@ # Mattermost Upgrade Guide -### Upgrading Mattermost v0.7 to v1.1.1 +### Upgrading Mattermost in GitLab 8.0 to GitLab 8.1 with omnibus -_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 to v1.1.1 and skipping the upgrade to Mattermost v1.0._ +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. -If you've manually changed Mattermost v0.7 configuration by updating the `config.json` file, you'll need to port those changes to Mattermost v1.1.1: +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). @@ -16,3 +29,5 @@ Optionally, you can use the new [System Console user interface](https://github.c + + diff --git a/doc/integrations/Single-Sign-On/Gitlab.md b/doc/integrations/Single-Sign-On/Gitlab.md index 0a8a1bd18..7939c47fb 100644 --- a/doc/integrations/Single-Sign-On/Gitlab.md +++ b/doc/integrations/Single-Sign-On/Gitlab.md @@ -1,6 +1,6 @@ ## 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. +Follow these steps 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: @@ -18,6 +18,6 @@ The following steps can be used to configure Mattermost to use GitLab as a singl Note: Make sure your `HTTPS` or `HTTP` prefix for endpoint URLs matches your server configuration. -5. (Optional) If you would like to force all users to sign-up with GitLab only, in the _ServiceSettings_ section of config/config.json please set _DisableEmailSignUp_ to `true`. +5. (Optional) If you would like to force all users to sign-up with GitLab only, in the _ServiceSettings_ section of config/config.json set _DisableEmailSignUp_ to `true`. 6. Restart your Mattermost server to see the changes take effect. diff --git a/doc/integrations/webhooks/Incoming-Webhooks.md b/doc/integrations/webhooks/Incoming-Webhooks.md index 7340282be..b5ae0fde2 100644 --- a/doc/integrations/webhooks/Incoming-Webhooks.md +++ b/doc/integrations/webhooks/Incoming-Webhooks.md @@ -4,8 +4,8 @@ Incoming webhooks allow external applications, written in the programming langua A couple key points: -- **Mattermost incoming webhooks are Slack-compatible.** If you've used Slack's incoming webhooks to create integrations, you can copy and paste that code to create Mattermost integrations. Mattermost automatically translates Slack's propretiary JSON payload format into markdown to render in Mattermost messages. -- **Mattermost incoming webhooks support full markdown.** A rich range of formatting unavailable in Slack is made possible through [markdown support](../../usage/Markdown.md) in Mattermost, incuding headings, formatted fonts, tables, inline images and other options supported by [Mattermost Markdown]. +- **Mattermost incoming webhooks are Slack-compatible.** If you've used Slack's incoming webhooks to create integrations, you can copy and paste that code to create Mattermost integrations. Mattermost automatically translates Slack's proprietary JSON payload format into markdown to render in Mattermost messages +- **Mattermost incoming webhooks support full markdown.** A rich range of formatting unavailable in Slack is made possible through [markdown support](../../usage/Markdown.md) in Mattermost, including headings, formatted fonts, tables, inline images and other options supported by [Mattermost Markdown] _Example:_ @@ -37,10 +37,10 @@ Which would render in a Mattermost message as follows: ### Enabling Incoming Webhooks Incoming webhooks should be enabled on your Mattermost instance by default, but if they are not you'll need to get your system administrator to enable them. If you are the system administrator you can enable them by doing the following: -1. Login to your Mattermost team account that has the system administrator role. -1. Enable incoming webhooks from **System Console -> Service Settings**. -1. (Optional) Configure the **Enable Overriding of Usernames from Webhooks** option to allow external applications to post messages under any name. If not enabled, the username of the creator of the webhook URL is used to post messages. -2. (Optional) Configure the **Enable Overriding of Icon from Webhooks** option to allow external applciations to change the icon of the account posting messages. If not enabled, the icon of the creator of the webhook URL is used to post messages. +1. Login to your Mattermost team account that has the system administrator role +1. Enable incoming webhooks from **System Console -> Service Settings** +1. (Optional) Configure the **Enable Overriding of Usernames from Webhooks** option to allow external applications to post messages under any name. If not enabled, the username of the creator of the webhook URL is used to post messages +2. (Optional) Configure the **Enable Overriding of Icon from Webhooks** option to allow external applciations to change the icon of the account posting messages. If not enabled, the icon of the creator of the webhook URL is used to post messages ### Setting Up Existing Integrations If you've already found or built an integration and are just looking to hook it up, then you should just need to follow the specific instructions of that integration. If the integration is using Mattermost incoming webhooks, then at some point in the instructions it will ask for a webhook URL. You can get this URL by following the first step in the next section _Creating Integrations using Incoming Webhooks_. @@ -54,43 +54,45 @@ You can create a webhook integration to post into Mattermost channels and privat 1. Login to your Mattermost team site and go to **Account Settings -> Integrations** 2. Next to **Incoming Webhooks** click **Edit** 3. Select the channel or private group to receive webhook payloads, then click **Add** to create the webhook - 4. To see your new webhook in action, try a curl command from your terminal or command-line to send a JSON string as the `payload` parameter in a HTTP POST request. + 4. To see your new webhook in action, try a curl command from your terminal or command-line to send a JSON string as the `payload` parameter in a HTTP POST request 1. Example: ``` curl -i -X POST -d 'payload={"text": "Hello, this is some text."}' http://yourmattermost.com/hooks/xxx-generatedkey-xxx ``` 3. Build your integration in the programming language of your choice - 1. Most integrations will be used to translate some sort of output from another system to an appropriately formatted input that will be passed into the Mattermost webhook URL. For example, an integration could take events generated by [GitLab outgoing webhooks](http://doc.gitlab.com/ee/web_hooks/web_hooks.html) and parse them into a JSON body to post into Mattermost. - 1. To get the message posted into Mattermost, your integration will need to create an HTTP POST request that will submit to the incoming webhook URL you created before. The body of the request must have a `payload` that contains a JSON object that specifies a `text` parameter. For example, `payload={"text": "Hello, this is some text."}` is a valid body for a request. - 2. Setup your integration running on Heroku, an AWS server or a server of your own to start sending real time updates to Mattermost channels and private groups. + 1. Most integrations will be used to translate some sort of output from another system to an appropriately formatted input that will be passed into the Mattermost webhook URL. For example, an integration could take events generated by [GitLab outgoing webhooks](http://doc.gitlab.com/ee/web_hooks/web_hooks.html) and parse them into a JSON body to post into Mattermost + 1. To get the message posted into Mattermost, your integration will need to create an HTTP POST request that will submit to the incoming webhook URL you created before. The body of the request must have a `payload` that contains a JSON object that specifies a `text` parameter. For example, `payload={"text": "Hello, this is some text."}` is a valid body for a request + 2. Set up your integration running on Heroku, an AWS server or a server of your own to start sending real time updates to Mattermost channels and private groups Additional Notes: 1. For the HTTP request body, if `Content-Type` is specified as `application/json` in the headers of the HTTP request then the body of the request can be direct JSON. For example, ```{"text": "Hello, this is some text."}``` -2. You can override the channel specified in the webhook definition by specifying a `channel` parameter in your payload. For example, you might have a single webhook created for _Town Square_, but you can use ```payload={"channel": "off-topic", "text": "Hello, this is some text."}``` to send a message to the _Off-Topic_ channel using the same webhook URL. +2. You can override the channel specified in the webhook definition by specifying a `channel` parameter in your payload. For example, you might have a single webhook created for _Town Square_, but you can use ```payload={"channel": "off-topic", "text": "Hello, this is some text."}``` to send a message to the _Off-Topic_ channel using the same webhook URL -1. In addition, with **Enable Overriding of Usernames from Webhooks** turned on, you can also override the username the message posts as by providing a `username` parameter in your JSON payload. For example, you might want your message looking like it came from a robot so you can use ```payload={"username": "robot", "text": "Hello, this is some text."}``` to change the username of the post to robot. Note, to combat any malicious users from trying to use this to perform [phishing attacks](https://en.wikipedia.org/wiki/Phishing) a `BOT` indicator appears next to posts coming from incoming webhooks. +1. In addition, with **Enable Overriding of Usernames from Webhooks** turned on, you can also override the username the message posts as by providing a `username` parameter in your JSON payload. For example, you might want your message looking like it came from a robot so you can use ```payload={"username": "robot", "text": "Hello, this is some text."}``` to change the username of the post to robot. Note, to combat any malicious users from trying to use this to perform [phishing attacks](https://en.wikipedia.org/wiki/Phishing) a `BOT` indicator appears next to posts coming from webhooks -2. With **Enable Overriding of Icon from Webhooks** turned on, you can similarly change the icon the message posts with by providing a link to an image in the `icon_url` parameter of your payload. For example, ```payload={"icon_url": "http://somewebsite.com/somecoolimage.jpg", "text": "Hello, this is some text."}``` will post using whatever image is located at `http://somewebsite.com/somecoolimage.jpg` as the icon for the post. +2. With **Enable Overriding of Icon from Webhooks** turned on, you can similarly change the icon the message posts with by providing a link to an image in the `icon_url` parameter of your payload. For example, ```payload={"icon_url": "http://somewebsite.com/somecoolimage.jpg", "text": "Hello, this is some text."}``` will post using whatever image is located at `http://somewebsite.com/somecoolimage.jpg` as the icon for the post -3. Also, as mentioned previously, [markdown](../../usage/Markdown.md) can be used to create richly formatted payloads, for example: ```payload={"text": "# A Header\nThe _text_ below **the** header."}``` creates a messages with a header, a carriage return and bold text for "the". +3. Also, as mentioned previously, [markdown](../../usage/Markdown.md) can be used to create richly formatted payloads, for example: ```payload={"text": "# A Header\nThe _text_ below **the** header."}``` creates a messages with a header, a carriage return and bold text for "the" -4. Just like regular posts, the text will be limited to 4000 characters at maximum. +4. Just like regular posts, the text will be limited to 4000 characters at maximum ### Slack Compatibility As mentioned above, Mattermost makes it easy to take integrations written for Slack's proprietary JSON payload format and repurpose them to become Mattermost integrations. The following automatic translations are supported: -1. Payloads designed for Slack using `<>` to note the need to hyperlink a URL, such as ```payload={"text": "<http://www.mattermost.com/>"}```, are translated to the equivalent markdown in Mattermost and rendered the same as you would see in Slack. -2. Similiarly, payloads designed for Slack using `|` within a `<>` to define linked text, such as ```payload={"text": "Click <http://www.mattermost.com/|here> for a link."}```, are also translated to the equivalent markdown in Mattermost and rendered the same as you would see in Slack. -3. Like Slack, by overriding the channel name with an @username, such as payload={"text": "Hi", channel: "@jim"}, you can send the message to a user through your direct message chat. -4. Channel names can be prepended with a #, like they are in Slack incoming webhooks, and the message will still be sent to the correct channel. +1. Payloads designed for Slack using `<>` to note the need to hyperlink a URL, such as ```payload={"text": "<http://www.mattermost.com/>"}```, are translated to the equivalent markdown in Mattermost and rendered the same as you would see in Slack +2. Similiarly, payloads designed for Slack using `|` within a `<>` to define linked text, such as ```payload={"text": "Click <http://www.mattermost.com/|here> for a link."}```, are also translated to the equivalent markdown in Mattermost and rendered the same as you would see in Slack +3. Like Slack, by overriding the channel name with an @username, such as payload={"text": "Hi", channel: "@jim"}, you can send the message to a user through your direct message chat +4. Channel names can be prepended with a #, like they are in Slack incoming webhooks, and the message will still be sent to the correct channel To see samples and community contributions, please visit <http://mattermost.org/webhooks>. -#### Limitations +#### Known Issues in v1.1 - The `attachments` payload used in Slack is not yet supported -- Overriding of usernames does not yet apply to notifications +- Overriding of usernames does not yet apply to notifications (fixed on master) +- Cannot supply `icon_emoji` to override the message icon +- Webhook UI fails when connected to deleted channel (fixed on master) diff --git a/doc/integrations/webhooks/Outgoing-Webhooks.md b/doc/integrations/webhooks/Outgoing-Webhooks.md new file mode 100644 index 000000000..008245715 --- /dev/null +++ b/doc/integrations/webhooks/Outgoing-Webhooks.md @@ -0,0 +1,120 @@ +# Outgoing Webhooks + +#### [To be released in Mattermost v1.2, available now on master] + +Outgoing webhooks allow external applications, written in the programming language of your choice--to receive HTTP POST requests whenever a user posts to a certain channel, with a trigger word at the beginning of the message, or a combination of both. If the external application responds appropriately to the HTTP request, as response post can be made in the channel where the original post occurred. + +A couple key points: + +- **Mattermost outgoing webhooks are Slack-compatible.** If you've used Slack's outgoing webhooks to create integrations, you can copy and paste that code to create Mattermost integrations. Mattermost automatically translates Slack's proprietary JSON payload format into markdown to render in Mattermost messages +- **Mattermost outgoing webhooks support full markdown.** When an integration responds with a message to post, it will have access to a rich range of formatting unavailable in Slack that is made possible through [markdown support](../../usage/Markdown.md) in Mattermost. This includes headings, formatted fonts, tables, inline images and other options supported by [Mattermost Markdown] + +_Example:_ + +Suppose you had an external application that recieved a post event whenever a message starting with `#build`. If a user posted the message `#build Let's see the status`, then the external application would receive an HTTP POST with data about that message. The application could then respond with a table of total tests run and total tests failed by component category, with links to failed tests by category. An example response might be: +``` +{"text": " +--- +##### Build Break - Project X - December 12, 2015 - 15:32 GMT +0 +| Component | Tests Run | Tests Failed | +|:-----------|:------------|:-----------------------------------------------| +| Server | 948 | :white_check_mark: 0 | +| Web Client | 123 | :warning: [2 (see details)](http://linktologs) | +| iOS Client | 78 | :warning: [3 (see details)](http://linktologs) | +--- +"} +``` +Which would render in a Mattermost message as follows: + +--- +##### Build Break - Project X - December 12, 2015 - 15:32 GMT +0 +| Component | Tests Run | Tests Failed | +|:-----------|:------------|:-----------------------------------------------| +| Server | 948 | :white_check_mark: 0 | +| Web Client | 123 | :warning: [2 (see details)](http://linktologs) | +| iOS Client | 78 | :warning: [3 (see details)](http://linktologs) | +--- + +### Enabling Outgoing Webhooks +Outgoing webhooks should be enabled on your Mattermost instance by default, but if they are not you'll need to get your system administrator to enable them. If you are the system administrator you can enable them by doing the following: + +1. Login to your Mattermost team account that has the system administrator role. +1. Enable outgoing webhooks from **System Console -> Service Settings**. +1. (Optional) Configure the **Enable Overriding of Usernames from Webhooks** option to allow external applications to post messages under any name. If not enabled, the username of the creator of the webhook URL is used to post messages. +2. (Optional) Configure the **Enable Overriding of Icon from Webhooks** option to allow external applciations to change the icon of the account posting messages. If not enabled, the icon of the creator of the webhook URL is used to post messages. + +### Set Up an Outgoing Webhook +Once outgoing webhooks are enabled, you will be able to set one up through the Mattermost UI. You will need to know the following + +1. The channel (if not all of them) you want to listen to post events from +2. The trigger words (if any) that will trigger a post event if they are the **first word** of the post +3. The URL you want Mattermost to report the events to + +Once you have those, you can follow these steps to set up your webhook: + +1. Login to your Mattermost team site and go to **Account Settings -> Integrations** +2. Next to **Outgoing Webhooks** click **Edit** +3. Under **Add a new outgoing webhook** select your options + 1. Select a channel from the **Channel** dropdown to only report events from a certain channel (optional if Trigger Words selected) + 2. Enter comma separated words into **Trigger Words** to only report events from posts that start with one of those words (optional if **Channel** selected) + 3. Enter new line separated URLs that the post events will be sent too +4. Click **Add** to add your webhook to the system +5. Your new outgoing webhook will be displayed below with a **Token** that any external application that wants to listen to the webhook should ask for in it's instructions + +### Creating Integrations using Outgoing Webhooks + +If you'd like to build your own integration that uses outgoing webhooks, you can follow these general guidelines: + +1. In the programming language of your choice, write your integration to perform what you had in mind + 1. Your integration should have a function for receiving HTTP POSTs from Mattermost that look like this example: + ``` + Content-Length: 244 + User-Agent: Go 1.1 package http + Host: localhost:5000 + Accept: application/json + Content-Type: application/x-www-form-urlencoded + + channel_id=hawos4dqtby53pd64o4a4cmeoo& + channel_name=town-square& + team_domain=someteam& + team_id=kwoknj9nwpypzgzy78wkw516qe& + text=some text here& + timestamp=1445532266& + token=zmigewsanbbsdf59xnmduzypjc& + trigger_word=some& + user_id=rnina9994bde8mua79zqcg5hmo& + user_name=somename + ``` + 2. Your integration must have a configurable **MATTERMOST_TOKEN** variable that is the Token given to you when you set up the outgoing webhook in Mattermost as decribed in the previous section _Set Up an Outgoing Webhook_. This configurable **MATTERMOST_TOKEN** must match the token in the request body so your application can be sure the request came from Mattermost + 3. If you want your integration to post a message back to the same channel, it can respond to the HTTP POST request from Mattermost with a JSON response body similar to this example: + ``` + { + "text": "This is some response text." + } + ``` +3. Set up your integration running on Heroku, an AWS server or a server of your own to start getting real time post events from Mattermost channels + +Additional Notes: + +1. With **Enable Overriding of Usernames from Webhooks** turned on, you can also override the username the message posts as by providing a `username` parameter in your JSON payload. For example, you might want your message looking like it came from a robot so you can use the JSON response ```{"username": "robot", "text": "Hello, this is some text."}``` to change the username of the post to robot. Note, to combat any malicious users from trying to use this to perform [phishing attacks](https://en.wikipedia.org/wiki/Phishing) a `BOT` indicator appears next to posts coming from webhooks + +2. With **Enable Overriding of Icon from Webhooks** turned on, you can similarly change the icon the message posts with by providing a link to an image in the `icon_url` parameter of your JSON response. For example, ```{"icon_url": "http://somewebsite.com/somecoolimage.jpg", "text": "Hello, this is some text."}``` will post using whatever image is located at `http://somewebsite.com/somecoolimage.jpg` as the icon for the post + +3. Also, as mentioned previously, [markdown](../../usage/Markdown.md) can be used to create richly formatted payloads, for example: ```payload={"text": "# A Header\nThe _text_ below **the** header."}``` creates a messages with a header, a carriage return and bold text for "the" + +4. Just like regular posts, the text will be limited to 4000 characters at maximum + +### Slack Compatibility + +As mentioned above, Mattermost makes it easy to take integrations written for Slack's proprietary JSON payload format and repurpose them to become Mattermost integrations. The following automatic translations are supported: + +1. The HTTP POST request body is formatted the same as Slack's, which means your Slack integration's receiving function should not need to change at all to be compatible with Mattermost +2. JSON responses designed for Slack using `<>` to note the need to hyperlink a URL, such as ```{"text": "<http://www.mattermost.com/>"}```, are translated to the equivalent markdown in Mattermost and rendered the same as you would see in Slack +3. Similiarly, responses designed for Slack using `|` within a `<>` to define linked text, such as ```{"text": "Click <http://www.mattermost.com/|here> for a link."}```, are also translated to the equivalent markdown in Mattermost and rendered the same as you would see in Slack + +To see samples and community contributions, please visit <http://mattermost.org/webhooks>. + +#### Known Issues in v1.1 + +- Overriding of usernames does not yet apply to notifications +- Cannot supply `icon_emoji` to override the message icon diff --git a/doc/process/documentation-guidelines.md b/doc/process/documentation-guidelines.md new file mode 100644 index 000000000..f37f0c5fc --- /dev/null +++ b/doc/process/documentation-guidelines.md @@ -0,0 +1,185 @@ +# Documentation Conventions + +The most important thing about documentation is getting it done and out to the community. + +After that, we can work on upgrading the quality of documentation. The below chart summarizes the different levels of documentation and how the quality gates are applied. + +_Note: Documentation Guidelines are new, and iterating. Documentation has started to balloon and this is our attempt at reducing ambiguity and increasing consistency, but the conventions here are very open to discussion._ + +| Stars | Benchmark | Timeline | +|:-------------|:--------------------------------|:--------------------------------| +| 1 | Documentation is correct. | First draft checked in by developer. Okay to ship in first release of new feature. | +| 2 | Documentation a) follows all objective formatting criteria, b) is tested by someone other than the author, c) satisfies above. | First edit under objective rules. Required before second release cycle with this feature included. | +| 3 | Documentation a) follows all subjective style criteria, b) is reviewed and edited by someone who has previously authored 3-star documentation, and c) satisfies above. | Second edit under subjective rules. Required before third release cycle with this feature included | +| 4 | Documentation a) has received at least 1 edit due to user feedback, b) has received at least one unprompted compliment from user community on quality, c) satisfies above. | Additional edits to refine documentation based on user feedback | + +## 1-Star Requirements: Correctness + +### List precise dependencies + +1. Be explicit about what specific dependencies have been tested as part of an installation procedure. +2. Be explicit about assumptions of compatibility on systems that have not been tested. +3. Do not claim the system works on later versions of a platform if backwards compatibility is not a priority for the dependency (It's okay to say Chrome version 43 and higher, but not Python 2.6 and higher, because Python 3.0 is explicitly incompatible with previous versions). + +#### Correct + +---- +This procedure works on an Ubuntu 14.04 server with Python 2.6 installed and should work on compatible Linux-based operating systems and compatible versions of Python. + +---- +#### Incorrect + +---- +This procedure works on Linux servers running Python. + +also: + +This procedure works on Linux servers running Python 2.6 and higher. + +---- +## 2-Star Requirements: Objective Formatting Checklist + +### Use headings + +Headings in markdown provide anchors that can be used to easily reference sub-sections of long pieces of documentation. This is preferrable to just numbering sections without headings. + +##### Correct: + +---- +##### Step 1: Add a heading +This makes things easier to reference via hyperlinks +##### Step 2: Link to headings +So things are eariser to find + +---- +##### Incorrect: + +---- +**Step 1: Add a heading** +This makes things easier to reference via hyperlinks +**Step 2: Link to headings** +So things are eariser to find +---- + +### Use appropriate heading case + +Cases in headings may vary depending on usage. + +#### When to use Title Case + +H1, H2, H3 headings should be "Title Case" and less than four words, except if a colon is used, then four words per segment separated by the colon. + +These large headings are typically shorter and help with navigating large documents + +#### When to use sentence case + +H3, H4, H5 headings should be "Sentence case" and can be any length. + +These headers are smaller and used to summarize sections. H3 can be considered either a large or small heading. + +These conventions are new, so there's flexibility around them, when you're not sure, consider the convention here as default. + +### One instruction per line + +It's easy to miss instructions when they're compounded. Have only one instruction per line, so documentation looks more like a checklist. + +A support person should be able to say "Did you complete step 7?" instead of "Did you complete the second part of step 7 after doing XXX?" + +##### Correct: + +---- + +6. For **Predefined configuration** look under **Generic** and select **Docker**. + 7. For **Environment type** select **Single instance** + +---- + +##### Incorrect: + +---- + +6. For **Predefined configuration** look under **Generic** and select **Docker**. For **Environment type** select **Single instance** + +---- + +### Lists end without periods + +Sentences within bullet points or numbered lists should end in normal punctuation. The sentence or fragment at the end of a bullet point should not have a period. + +##### Correct + +---- +- This is a sentence within a bullet point. This is the end of a bullet point without a period + +---- +##### Incorrect + +---- +- This is an incorrect ending of a bullet point with a period. + +---- +### Avoid Passive Phrases + +Examples of passive phrases include "have", "had", "was", "can be", "has been" and documentation is shorter and clearer without them. + +##### Correct + +---- +This software **runs** on any server that supports Python. + +---- +##### Incorrect + +---- +This software **can be run** on any server that supports Python. + +---- +## 3-Star Requirements: Subjective Style Guidelines + +### Be Concise + +Try to use fewer words when possible. + +##### Correct: + +---- +This integration posts [issue](http://doc.gitlab.com/ee/web_hooks/web_hooks.html#issues-events), [comment](http://doc.gitlab.com/ee/web_hooks/web_hooks.html#comment-events) and [merge request](http://doc.gitlab.com/ee/web_hooks/web_hooks.html#merge-request-events) events from a GitLab repository into specific Mattermost channels by formatting output from [GitLab's outgoing webhooks](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/web_hooks/web_hooks.md) to [Mattermost's incoming webhooks](https://github.com/mattermost/platform/blob/master/doc/integrations/webhooks/Incoming-Webhooks.md). + +---- +##### Incorrect: + +---- +This integration makes use of GitLab's outgoing webhooks and Mattermost's incoming webhooks to post GitLab events into Mattermost. You can find GitLab's outgoing webhooks described [here](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/web_hooks/web_hooks.md) and Mattermost's incoming webhooks described [here](https://github.com/mattermost/platform/blob/master/doc/integrations/webhooks/Incoming-Webhooks.md). + +---- + +### Use appropriate emphasis + +Mention Clickable Controls in **Bold**, Sections and Setting Names in *Italics*, and Key Strokes in `pre-formatted text`. + +To make it clear and consistent across documentation on how we describe controls that a user is asked to manipulate, we have a number of guidelines: + +**Bold** +- Please **bold** the names of controls you're asking users to click. The text that is bolded should match the label of the control in the user interface. Do not format these references with _italics_, ALL-CAPS or `pre-formatted text`. +- Use `>` to express a series of clicks, for example clicking on **Button One** > **Button Two** > **Button Three**. +- If a button might be difficult to find, give a hint about its location _before_ mentioning the name of the control (this helps people find the hint before they start searching, if the see the name of the button first, they might not continue reading to find the hint before starting to look). + +***Italics*** +- Please *italicize* setting names or section headings that identify that the user is looking in the correct area. The text that is italicized should match the name of the setting or section in the user interface. +- It is helpful to use italics to guide the user to the correct area before mentioning a clickable action in bold. + +**`pre-formatted text`** +- Please use `pre-formatted text` to identify when a user must enter key strokes or paste text into an input box. + +#### Correct + +---- +Type `mattermost-integration-giphy` in the *repo-name* field, then click **Search** and then the **Connect** button once Heroku finds your repository + +---- +#### Incorrect + +---- +Type "mattermost-integration-giphy" in the **repo-name** field, then click Search and then the *Connect* button once Heroku finds your repository + +---- diff --git a/doc/process/release-process.md b/doc/process/release-process.md new file mode 100644 index 000000000..04ec9a366 --- /dev/null +++ b/doc/process/release-process.md @@ -0,0 +1,99 @@ +We're working on making internal processes in the Mattermost core team more transparent for the community. Below is a working draft of our software development process, which will be updated live as we refine our process. + +Questions, feedback, comments always welcome, + +---------- + +Mattermost core team works on a monthly release process, with a new version shipping on the 16th of each month. + +This document outlines the development process for the Mattermost core team, which draws from what we find works best for us from Agile, Scrum and Software Development Lifecycle approaches. + +This is a working document that will update as our process evolves. + + +### - Beginning of release +- (Ops) Queue an agenda item for first team meeting of the release to review Roadmap + +### - (10 weekdays before release date) Cut-off for major features +- No major features can be committed to the current release after this date +- (Dev) Prioritize reviewing, updating, and merging of all pull requests that are going to make it into the release + - There should be no more tickets in the [pull request queue](https://github.com/mattermost/platform/pulls) marked for the current release +- (Leads) Meets to prioritize the final tickets of the release + - Backlog is reviewed and major features that won’t make it are moved to next release + - Triage tickets + - Review roadmap for next release +- (Marketing) Writes the "Highlights" section of the Changelog +- (PM) Write compatibility updates for config.json and database changes [See example](https://github.com/mattermost/platform/blob/master/CHANGELOG.md#compatibility) +- (PM) Update [Upgrade Guide](https://github.com/mattermost/platform/blob/master/doc/install/Upgrade-Guide.md) for any steps needed to upgrade to new version +- (PM) Prepare tickets for cutting RCs builds, filing issue in GitLab omnibus to take RC candidate, testing GitLab RC with Mattermost +- (Stand-up) Each team member discusses worst bug + +### - (8 weekdays before release date) Feature Complete and Stabilization +- After the cut-off time for Feature Complete, Dev prioritizes reviewing PRs and committing to master so Stabilization period can begin, with testing and high priority bug fixes +- During Stabilization period only BUGS can be committed to master, non-bug tickets are tagged for next version and wait until after a release candidate is cut to be added to master + - (PM) Review all [S1 bugs](https://mattermost.atlassian.net/secure/IssueNavigator.jspa?mode=hide&requestId=10600) and mark important ones as high priority + - (Dev + PM) Exceptions can be made by triage team consensus across PM and Dev. List of approved changes for release candidate 1 here: https://mattermost.atlassian.net/issues/?filter=10204 +- (PM) Documentation + - (PM) Make Changelog PR with updates for latest feature additions and changes + - (PM) Make Changelog PR with updates to contributors + - (PM) Make NOTICE.txt PR for any new libraries added from dev, if not added already + - (PM) Prioritize any developer documentation tickets +- (PM and devs) Sign-off testing of their feature areas (i.e. PM/dev either signs-off that their area is well tested, or they flag that potential quality issues may exist) +- (Ops) Mail out mugs to any new contributors +- (Team) Select "Top Contributor" for the release from external contributions to be mentioned in release announcement +- (Marketing) Decides announce date (discuss in meeting) +- (Ops) Post Announce Date in Release channel + update the channel header to reflect date +- (Marketing) Communicates checklist of items needed by specific dates to write the blog post announce (eg screenshots, GIFs, documentation) and begins to write the blog post, tweet, and email for the release announcement +- (PM) Works with Ops to check the Quality Gate for feature complete +- (PM) Communicate to team the plan for next release +- (Stand-up) Each team member discusses worst bug + +### - (5 weekdays before release date) Code Compete and Release Candidate Cut +- (Team) Meets to discuss release at 10am PST + - (PM) Each area changed in latest release is assigned a PM owner to lead testing + - (Ops) Walks through each item of the **Code Complete and Release Candidate Cut** checklist + - (Dev) Last check of tickets that need to be merged before RC1 + - (Team) Each team member discusses worst bug +- After 10am PST meeting the release is considered “Code Complete”. + - (Dev) Completes final reviews and updates of PRs marked for the release version + - There should be no more tickets in the [pull request queue](https://github.com/mattermost/platform/pulls) marked for the current release + - Master is tagged and branched and “Release Candidate 1″ is cut (e.g. 1.1.0-RC1) according to the Release Candidate Checklist + - (PM) Create meta issue for regressions in GitHub (see [example](https://github.com/mattermost/platform/issues/574)) + +### - (4 weekdays before release date) Release Candidate Testing +- Final testing is conducted by the team on the acceptance server and any issues found are filed + - (Dev) Tests upgrade from previous version to current version, following the [Upgrade Guide](https://github.com/mattermost/platform/blob/master/doc/install/Upgrade-Guide.md) + - (Ops) Posts copy of the **Release Candidate Testing** checklist into Town Square in PRODUCTION + - (Ops) Moves meeting, test and community channels over to the production version of RC, and posts in Town Square asking everyone to move communication over to the new team for testing purposes + - (PM) Test feature areas and post bugs to Bugs/Issues in PRODUCTION + - (Ops) Runs through general testing checklist on RC1 and post bugs to Bugs/Issues in PRODUCTION + - (PM & DEV) Add **#p1** tag to any “Blocking” issue that looks like a hotfix to the RC is needed, and create a public ticket in Jira. Blocking issues are considered to be security issues, data loss issues, issues that break core functionality, or significantly impact aesthetics. +- (PM) Updates the GitHub meta issue + - (PM) Posts links to all issues found in RC as comments on the meta issue + - (PM) Updates description to include approved fixes + - (PM) Posts screenshot and link to final tickets for next RC to the Release room +- (PM & DEV leads) Triage hotfix candidates and decide on whether and when to cut next RC or final +- (Dev) PRs for hotfixes made to release branch, and changes from release branch are merged into master + - (Ops) Tests approved fixes on master + - (Dev) Pushes next RC to acceptance after testing is complete and approved fixes merged +- (Dev) pushes next RC to acceptance and announces in Town Square on PRODUCTION + - (PM) closes the meta issue after the next RC is cut, and opens another ticket for new RC +- (Ops) verifies each of the issues in meta ticket is fixed + - (PM) If no blocking issues are found, PM, Dev and Ops signs off on the release + +### - (2 weekdays before release date) Release + - (Dev) Tags a new release (e.g. 1.1.0) and runs an official build which should be essentially identical to the last RC + - (PM) Any significant issues that were found and not fixed for the final release are noted in the release notes + - If an urgent and important issue needs to be addressed between major releases, a hotfix release (e.g. 1.1.1) may be released, however this should be very rare, given a monthly cadence + - (PM) Copy and paste the Release Notes from the Changelog to the Release Description + - (PM) Update the mattermost.org/download page + - (Dev) Delete RCs after final version is shipped + - (PM) Close final GitHub RC meta ticket + +### - (0 weekdays before release date) End of Release +- (PM) Makes sure marketing has been posted (animated GIFs, screenshots, mail announcement, Tweets, blog posts) +- (PM) Close the release in Jira +- (Dev) Check if any libraries need to be updated for the next release, and if so bring up in weekly team meeting +- (Ops) Post important dates for the next release in the header of the Release channel +- (Ops) Queue an agenda item for next team meeting for "Stepping Back" Q&A +- (Ops) Queue an agenda item for next team meeting for Roadmap review |