Installing Mattermost on Ubuntu 16.04 LTS¶

Installing Ubuntu Server 16.04 LTS¶

Install the 64-bit version of Ubuntu Server on each machine that hosts one or more of the components.

To install Ubuntu Server 16.04:

1. To install Ubuntu Server 16.04, see the Ubuntu Installation Guide.
2. After the system is installed, make sure that it’s up to date with the most recent security patches. Open a terminal window and issue the following commands:

sudo apt-get update

sudo apt-get upgrade

Now that the system is up to date, you can start installing the components that make up a Mattermost system.

Installing MySQL Database Server¶

Install and set up the database for use by the Mattermost server. You can install either MySQL or PostgreSQL.

To install MySQL on Ubuntu Server 16.04:

1. Log into the server that will host the database, and open a terminal window.
2. Install MySQL.

sudo apt-get install mysql-server

Note

During the install, you’ll be prompted to create a password for the MySQL root user. Make a note of the password because you’ll need it in the next step.

3. Log in to MySQL as root.

mysql -u root -p

When prompted, enter the root password that you created when installing MySQL.

4. Create the Mattermost user ‘mmuser’.

mysql> create user 'mmuser'@'%' identified by 'mmuser-password';

Note

1. Use a password that is more secure than ‘mmuser-password’.
2. The ‘%’ means that mmuser can connect from any machine on the network. However, it’s more secure to use the IP address of the machine that hosts Mattermost. For example, if you install Mattermost on the machine with IP address 10.10.10.2, then use the following command:

mysql> create user 'mmuser'@'10.10.10.2' identified by 'mmuser-password';

5. Create the Mattermost database.

mysql> create database mattermost;

6. Grant access privileges to the user ‘mmuser’.

mysql> grant all privileges on mattermost.* to 'mmuser'@'%';

7. Log out of MySQL.

   mysql> exit

With the database installed and the initial setup complete, you can now install the Mattermost server.

Installing PostgreSQL Database Server¶

Install and set up the database for use by the Mattermost server. You can install either PostgreSQL or MySQL.

Assume that the IP address of this server is 10.10.10.1

To install PostgreSQL on Ubuntu Server 16.04:

1. Log in to the server that will host the database and issue the following command:

sudo apt-get install postgresql postgresql-contrib

When the installation is complete, the PostgreSQL server is running, and a Linux user account called postgres has been created.

2. Log in to the postgres account.

sudo --login --user postgres

3. Start the PostgreSQL interactive terminal.

psql

4. Create the Mattermost database.

postgres=# CREATE DATABASE mattermost;

5. Create the Mattermost user ‘mmuser’.

postgres=# CREATE USER mmuser WITH PASSWORD 'mmuser_password';

Note

Use a password that is more secure than ‘mmuser-password’.

6. Grant the user access to the Mattermost database.

postgres=# GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser;

7. Exit the PostgreSQL interactive terminal.

postgre=# \q

8. Log out of the postgres account.

exit

9. Allow Postgres to listen on all assigned IP Addresses. Open /etc/postgresql/9.3/main/postgresql.conf as root in a text editor.

1. Find the following line:

#listen_addresses = 'localhost'

2. Uncomment the line and change localhost to *:

listen_addresses = '*'

10. If the Mattermost server is on a separate machine, modify the file pg_hbe.conf to allow the Mattermost server to communicate with the database.

If the Mattermost server and the database are on the same machine, then you can skip this step.

1. Open /etc/postgresql/9.3/main/pg_hba.conf in a text editor.
2. Add the following line to the end of the file, where <mm-server-IP> is the IP address of the machine that contains the Mattermost server.

host all all <mm-server-IP>/32 md5

11. Reload Postgres database.

sudo systemctl reload postgresql

12. Verify that you can connect with the user mmuser.

psql --host=localhost --dbname=mattermost --username=mmuser --password

The PostgreSQL interactive terminal starts. To exit the PostgreSQL interactive terminal, type \q and press Enter.

With the database installed and the initial setup complete, you can now install the Mattermost server.

Installing Mattermost Server¶

Install Mattermost Server on a 64-bit machine.

Assume that the IP address of this server is 10.10.10.2.

To install Mattermost Server on Ubuntu

1. Log in to the server that will host Mattermost Server and open a terminal window.
2. Download the latest version of the Mattermost Server. In the following command, replace X.X.X with the version that you want to download:

wget https://releases.mattermost.com/X.X.X/mattermost-X.X.X-linux-amd64.tar.gz

5. Extract the Mattermost Server files.

tar -xvzf mattermost*.gz

3. Move the extracted file to the /opt directory.

sudo mv mattermost /opt

4. Create the storage directory for files.

sudo mkdir /opt/mattermost/data

Note

The storage directory will contain all the files and images that your users post to Mattermost, so you need to make sure that the drive is large enough to hold the anticipated number of uploaded files and images.

5. Set up a system user and group called mattermost that will run this service, and set the ownership and permissions.

1. Create the Mattermost user and group:

sudo useradd --system --user-group mattermost

2. Set the user and group mattermost as the owner of the Mattermost files:

sudo chown -R mattermost:mattermost /opt/mattermost

3. Give write permissions to the mattermost group:

sudo chmod -R g+w /opt/mattermost

6. Set up the database driver in the file /opt/mattermost/config/config.json. Open the file in a text editor and make the following changes:

• If you are using PostgreSQL:

1. Set "DriverName" to "postgres"
2. Set "DataSource" to the following value, replacing <mmuser-password> and <host-name-or-IP> with the appropriate values:

"postgres://mmuser:<mmuser-password>@<host-name-or-IP>:5432/mattermost?sslmode=disable&connect_timeout=10".

• If you are using MySQL:

1. Set "DriverName" to "mysql"
2. Set "DataSource" to the following value, replacing <mmuser-password> and <host-name-or-IP> with the appropriate values:

"mmuser:<mmuser-password>@tcp(<host-name-or-IP>:3306)/mattermost?charset=utf8"

7. Test the Mattermost server to make sure everything works.

   1. Change to the bin directory:

   cd /opt/mattermost/bin

   2. Start the Mattermost server as the user mattermost:

   sudo -u mattermost /.platform

When the server starts, it shows some log information and the text Server is listening on :8065. You can stop the server by typing CTRL+C in the terminal window.

8. Setup Mattermost to use systemd for starting and stopping.

1. Create a systemd unit file:

sudo touch /lib/systemd/system/mattermost.service

2. Open the unit file as root in a text editor, and copy the following lines into the file:

[Unit]
Description=Mattermost
After=network.target
After=postgresql.service
Requires=postgresql.service

[Service]
Type=simple
ExecStart=/opt/mattermost/bin/platform
Restart=always
RestartSec=10
WorkingDirectory=/opt/mattermost
User=mattermost
Group=mattermost

[Install]
WantedBy=multi-user.target

Note

If you are using MySQL, replace postgresql.service with mysql.service in 2 places in the [Unit] section.

3. Make systemd load the new unit.

sudo systemctl daemon-reload

4. Check to make sure that the unit was loaded.

sudo systemctl status mattermost.service

You should see an output similar to the following:

● mattermost.service - Mattermost
  Loaded: loaded (/lib/systemd/system/mattermost.service; disabled; vendor preset: enabled)
  Active: inactive (dead)

5. Start the service.

sudo systemctl start mattermost.service

6. Verify that Mattermost is running.

curl http://localhost:8065

You should see the HTML that’s returned by the Mattermost server.

7. Set Mattermost to start on machine start up.

sudo systemctl enable mattermost.service

Now that the Mattermost server is up and running, you can do some initial configuration and setup.

Configuring Mattermost Server¶

1. Navigate to https://mattermost.example.com and create a team and user.

The first user in the system is automatically granted the system_admin role, which gives you access to the System Console.

2. Open the System Console. Click your username at the top left of navigation panel. In the menu that opens, click System Console.

3. Setup an SMTP email service. Click Notifications > Email and make the following changes. The example below assumes AmazonSES.

   1. Set Enable Email Notifications to true
   2. Set Notification Display Name to No-Reply
   3. Set Notification From Address to mattermost@example.com
   4. Set SMTP Server Username to [YOUR_SMTP_USERNAME]
   5. Set SMTP Server Password to [YOUR_SMTP_PASSWORD]
   6. Set SMTP Server to email-smtp.us-east-1.amazonaws.com
   7. Set SMTP Server Port to 465
   8. Set Connection Security to TLS
   9. Save the Settings

4. Click Files > Storage and change Local Storage Directory from ./data/ to /mattermost/data

5. Click General > Logging and set Output logs to console to false

6. Feel free to modify other settings.

7. Restart the Mattermost Service.

sudo restart mattermost

Configuring TLS on the Mattermost Server¶

1. Go to the General > Configuration section of the System Console.
2. Change the Listen Address setting to :443
3. Change the Connection Security setting to TLS
4. Change the Forward port 80 to 443 setting to true if you wish to redirect users that try to connect insecurely to a secure connection. If you’re using a proxy such as NGINX in front of Mattermost this setting is unnecessary and should be set to false
5. Run sudo setcap cap_net_bind_service=+ep ./bin/platform in your Mattermost directory to allow Mattermost to bind to low ports. You will need to re-run this command every time you upgrade Mattermost or it will fail to bind to the port.

At this point you have two options: automatic certificate retrieval though Let’s Encrypt or manually specifying a certificate.

Installing NGINX Server¶

In a production setting, use a proxy server for greater security and performance of Mattermost.

The main benefits of using a proxy are as follows:

• SSL termination
• HTTP to HTTPS redirect
• Port mapping :80 to :8065
• Standard request logs

To install NGINX on Ubuntu Server:

1. Log in to the server that will host the proxy and open a terminal window.
2. Install NGINX.

sudo apt-get install nginx

3. After the installation is complete, verify that NGINX is running.

curl http://localhost

If NGINX is running, you see the following output:

<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
.
.
.
<p><em>Thank you for using nginx.</em></p>
</body>
</html>

sudo service nginx stop
sudo service nginx start
sudo service nginx restart

What to do next

1. Map a fully qualified domain name (FQDN) such as mattermost.example.com to point to the NGINX server.
2. Configure NGINX to proxy connections from the internet to the Mattermost Server.

Configuring NGINX as a proxy for Mattermost Server¶

NGINX is configured using a file in the /etc/nginx/sites-available directory. You need to create the file and then enable it. When creating the file, you need the IP address of your Mattermost server and the fully qualified domain name (FQDN) of your Mattermost website.

To configure NGINX as a proxy

1. Log in to the server that hosts NGINX and open a terminal window.
2. Create a configuration file for Mattermost.

sudo touch /etc/nginx/sites-available/mattermost

3. Open the file /etc/nginx/sites-available/mattermost as root in a text editor and replace its contents, if any, with the following lines. Make sure that you use your own values for the Mattermost server IP address and FQDN for server_name.

upstream backend {
   server 10.10.10.2:8065;
}

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=mattermost_cache:10m max_size=3g inactive=120m use_temp_path=off;

server {
   listen 80;
   server_name    mattermost.example.com;

   location /api/v3/users/websocket {
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
       client_max_body_size 50M;
       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_buffers 256 16k;
       proxy_buffer_size 16k;
       proxy_read_timeout 600s;
       proxy_pass http://backend;
   }

   location / {
       client_max_body_size 50M;
       proxy_set_header Connection "";
       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_buffers 256 16k;
       proxy_buffer_size 16k;
       proxy_read_timeout 600s;
       proxy_cache mattermost_cache;
       proxy_cache_revalidate on;
       proxy_cache_min_uses 2;
       proxy_cache_use_stale timeout;
       proxy_cache_lock on;
       proxy_pass http://backend;
   }
}

4. Remove the existing default sites-enabled file.

sudo rm /etc/nginx/sites-enabled/default

5. Enable the mattermost configuration.

sudo ln -s /etc/nginx/sites-available/mattermost /etc/nginx/sites-enabled/mattermost

6. Restart NGINX.

On Ubuntu 14.04 and RHEL 6.6:

sudo service nginx restart

On Ubuntu 16.04 and RHEL 7.1:

sudo systemctl restart nginx

7. Verify that you can see Mattermost through the proxy.

curl http://localhost

If everything is working, you will see the HTML for the Mattermost signup page.

What to do next

You can configure NGINX to use SSL, which allows you to use HTTPS connections and the HTTP/2 protocol.

Configuring NGINX with SSL and HTTP/2¶

Using SSL gives greater security by ensuring that communications between Mattermost clients and the Mattermost server are encrypted. It also allows you to configure NGINX to use the HTTP/2 protocol.

Although you can configure HTTP/2 without SSL, both Firefox and Chrome browsers support HTTP/2 on secure connections only.

You can use any certificate that you want, but these instructions show you how to download and install certificates from Let’s Encrypt, a free certificate authority.

To configure SSL and HTTP/2:

1. Log in to the server that hosts NGINX and open a terminal window.
2. Install git.

If you are using Ubuntu or Debian:

sudo apt-get install git

If you are using RHEL:

sudo yum install git

3. Clone the Let’s Encrypt repository on GitHub.

git clone https://github.com/letsencrypt/letsencrypt

4. Change to the letsencrypt directory.

cd letsencrypt

5. Stop NGINX.

On Ubuntu 14.04 and RHEL 6.6:

sudo service nginx stop

On Ubuntu 16.04 and RHEL 7.1:

sudo systemctl stop nginx

6. Run netstat to make sure that nothing is listening on port 80.

netstat -na | grep ':80.*LISTEN'

7. Run the Let’s Encrypt installer.

./letsencrypt-auto certonly --standalone

When prompted, enter your domain name. After the installation is complete, you can find the certificate in the /etc/letsencrypt/live directory.

8. Open the file /etc/nginx/sites-available/mattermost as root in a text editor and update the server section to incorporate the highlighted lines in the following sample. Make sure to replace {domain-name} with your own domain name, in 3 places.

.
.
.
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=mattermost_cache:10m max_size=3g inactive=120m use_temp_path=off;

server {
   listen 80 default_server;
   server_name   {domain-name} ;
   return 301 https://$server_name$request_uri;
}

server {
  listen 443 ssl http2;
  server_name    . . . ;

  ssl on;
  ssl_certificate /etc/letsencrypt/live/{domain-name}/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/{domain-name}/privkey.pem;
  ssl_session_timeout 5m;
  ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
  ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH';
  ssl_prefer_server_ciphers on;
  ssl_session_cache shared:SSL:10m;
}

location /api/v3/users/websocket {
    proxy_set_header Upgrade $http_upgrade;
    .
    .
    .

9. Restart NGINX.

On Ubuntu 14.04 and RHEL 6.6:

sudo service nginx start

On Ubuntu 16.04 and RHEL 7.1:

sudo systemctl start nginx

10. Check that your SSL certificate is set up correctly.

• Test the SSL certificate by visiting a site such as https://www.ssllabs.com/ssltest/index.html
• If there’s an error about the missing chain or certificate path, there is likely an intermediate certificate missing that needs to be included.

11. Configure cron so that the certificate will automatically renew every month.

crontab -e

In the following line, use your own domain name in place of {domain-name}

@monthly /home/ubuntu/letsencrypt/letsencrypt-auto certonly --reinstall --nginx -d {domain-name} && sudo service nginx reload