(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 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.
  2. This can also be set up all on a single server for small teams:
  3. I have a Mattermost instance running on a single Debian Jessie server with 1GB of ram and 30 GB SSD
  4. This has been working in production for ~20 users without issue.
  5. The only difference in the below instructions for this method is to do everything on the same server
  6. Make sure the system is up to date with the most recent security patches.
  7. sudo apt-get update
  8. 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
  2. Install PostgreSQL 9.3+ (or MySQL 5.6+)
  3. sudo apt-get install postgresql postgresql-contrib
  4. PostgreSQL created a user account called postgres. You will need to log into that account with:
  5. sudo -i -u postgres
  6. You can get a PostgreSQL prompt by typing:
  7. psql
  8. Create the Mattermost database by typing:
  9. postgres=# CREATE DATABASE mattermost;
  10. Create the Mattermost user by typing:
  11. postgres=# CREATE USER mmuser WITH PASSWORD 'mmuser_password';
  12. Grant the user access to the Mattermost database by typing:
  13. postgres=# GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser;
  14. You can exit out of PostgreSQL by typing:
  15. postgre=# \q
  16. You can exit the postgres account by typing:
  17. 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
  2. Download the latest Mattermost Server by typing:
  3. wget https://github.com/mattermost/platform/releases/download/v1.1.0/mattermost.tar.gz
  4. Install Mattermost under /opt
  5. cd /opt
  6. Unzip the Mattermost Server by typing:
  7. tar -xvzf mattermost.tar.gz
  8. 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.
  9. Create the directory by typing:
  10. sudo mkdir -p /opt/mattermost/data
  11. Create a system user and group called mattermost that will run this service
  12. useradd -r mattermost -U
  13. Set the mattermost account as the directory owner by typing:
  14. sudo chown -R mattermost:mattermost /opt/mattermost
  15. Add yourself to the mattermost group to ensure you can edit these files:
  16. sudo usermod -aG mattermost USERNAME
  17. Configure Mattermost Server by editing the config.json file at /opt/mattermost/config
  18. cd /opt/mattermost/config
  19. Edit the file by typing:
  20. vi config.json
  21. replace DriverName": "mysql" with DriverName": "postgres"
  22. 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"
  23. 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.
  24. Test the Mattermost Server
  25. cd /opt/mattermost/bin
  26. Run the Mattermost Server by typing:
  27. ./platform
  28. You should see a console log like Server is listening on :8065 letting you know the service is running.
  29. Stop the server for now by typing ctrl-c
  30. Setup Mattermost to use the systemd init daemon which handles supervision of the Mattermost process
  31. sudo touch /etc/init.d/mattermost
  32. sudo vi /etc/init.d/mattermost
  33. 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

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
  2. We use Nginx for proxying request to the Mattermost Server. The main benefits are:
  3. SSL termination
  4. http to https redirect
  5. Port mapping :80 to :8065
  6. Standard request logs
  7. Install Nginx on Debian with
  8. sudo apt-get install nginx
  9. Verify Nginx is running
  10. curl http://10.10.10.3
  11. You should see a Welcome to nginx! page
  12. You can manage Nginx with the following commands
  13. sudo service nginx stop
  14. sudo service nginx start
  15. sudo service nginx restart
  16. Map a FQDN (fully qualified domain name) like mattermost.example.com to point to the Nginx server.
  17. Configure Nginx to proxy connections from the internet to the Mattermost Server
  18. Create a configuration for Mattermost
  19. sudo touch /etc/nginx/sites-available/mattermost
  20. 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.
  2. The first user in the system is automatically granted the system_admin role, which gives you access to the System Console.
  3. From the town-square channel click the dropdown and choose the System Console option
  4. Update Email Settings. We recommend using an email sending service. The example below assumes AmazonSES.
  5. Set Send Email Notifications to true
  6. Set Require Email Verification to true
  7. Set Feedback Name to No-Reply
  8. Set Feedback Email to mattermost@example.com
  9. Set SMTP Username to AFIADTOVDKDLGERR
  10. Set SMTP Password to DFKJoiweklsjdflkjOIGHLSDFJewiskdjf
  11. Set SMTP Server to email-smtp.us-east-1.amazonaws.com
  12. Set SMTP Port to 465
  13. Set Connection Security to TLS
  14. Save the Settings
  15. Update File Settings
  16. Change Local Directory Location from ./data/ to /mattermost/data
  17. Update Log Settings.
  18. Set Log to The Console to false
  19. Update Rate Limit Settings.
  20. Set Vary By Remote Address to false
  21. Set Vary By HTTP Header to X-Real-IP
  22. Feel free to modify other settings.
  23. Restart the Mattermost Service by typing:
  24. sudo restart mattermost