Installing Mattermost Messaging on Ubuntu 18.04

Mattermost Overview

Mattermost is an open-source messaging tool for inter-team communication, released under the MIT license and available both in a free team and paid enterprise edition. This tutorial will show you how to install a Mattermost instance with a NGINX frontend proxy and a MariaDB database.


Installing Mattermost

1 . Connect to your compute instance via SSH.

2 . Update the APT packet cache and the software already installed on the instance:

apt update && apt upgrade -y

3 . Install the MariaDB database server:

apt install mariadb-server

4 . Initialize the database server:


5 . Log into mysql as root:


6 . Create a database for Mattermost:

create user 'mattermost'@'localhost' identified by 'a-secure-password';

Important: Replace a-secure-password with a strong password, as it will be used to login to MariaDB

7 . Create a database for Mattermost whilst being logged into the MariaDB shell:

create database mattermost;

8 . Grant access privileges to the user mattermost:

grant all privileges on mattermost.* to 'mattermost'@'localhost';

9 . Exit the MariaDB shell:


10 . Download the latest version of the Mattermost server to your instance. At the time writing this tutorial it is version 5.7:


11 . Extract the Mattermost server files:

tar -xvzf mattermost*.gz

12 . Move the extracted files to the /opt directory:

mv mattermost /opt

13 . Create the storage directory for Mattermost:

mkdir /opt/mattermost/data

Important: This directory will contain all data sent to your Mattermost instance (Messages, Images, Files etc.). Make sure that it has enough space available for the anticipated number of contents sent to your instance.

14 . Set up a system user and group to be in charge of running the service and set the ownership and permissions as following:

  • Create a system user and group called mattermost:
    useradd --system --user-group mattermost
  • Set the ownership of the Mattermost files to the previously created user and group:
    chown -R mattermost:mattermost /opt/mattermost
  • Give write permissions to the mattermost group:
    chmod -R g+w /opt/mattermost

15 . Open the file /opt/mattermost/config/config.json with your favourite text editor and edit the database settings as following:

  • Set the "DriverName" to mysql
  • Configure "DataSource" as following, replacingwith the password you have set for your database:

16 . Start the Mattermost server manually to check everything is working:

sudo -u mattermost ./bin/mattermost

During startup the database structure of Mattermost will be configured and you will see some log messages as well as a notice: Server is listening on :8065. This means your Mattermost server is now ready to be used. Stop the process by pushing Control+C on your keyboard.

17 . Open your favourite text editor and create the file /lib/systemd/system/mattermost.service with the following content to create a systemd script to run the application as a service on your instance:




18 . Reload the systemd configuration:

systemctl daemon-reload

19 . Start the service:

systemctl start mattermost.service

20 . Enable the service to start Mattermost during the startup of the instance:

systemctl enable mattermost.service

You can now connect to your Mattermost server at http://your_servers_ip:8065 and create your first user and do some initial configuration and setup.

Installing a Nginx Proxy with Let's Encrypt

For security reasons it is recommended to put the application behind a proxy. Nginx is being used as frontend for the application. To provide an encrypted connection, certbot is used to generate a free Let’s Encrypt SSL certificate to encrypt the connection to the instance.

1 . Install Nginx and Certbot:

apt install nginx python-certbot-nginx -y

2 . Create a new server block for Mattermost (replace with the FQDN of your instance):

touch /etc/nginx/sites-available/

and put the following content into the file:

upstream backend {
   keepalive 32;

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;

   location ~ /api/v[0-9]+/(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;
       client_body_timeout 60;
       send_timeout 300;
       lingering_timeout 5;
       proxy_connect_timeout 90;
       proxy_send_timeout 300;
       proxy_read_timeout 90s;
       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_http_version 1.1;
       proxy_pass http://backend;

3 . Remove the default server block of Nginx:

rm /etc/nginx/sites-enabled/default

4 . Enable the Mattermost server block by linking it to the sites-enabled directory:

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

5 . Restart Nginx:

sudo service nginx restart

6 . Run Certbot:


Important: The application will ask you several questions. You have to confirm the steps as described. For more information refer to our documentation about certbot.

7 . Connect to your instance by going to https://your_servers_ip. The Mattermost login screen will appear. Connect yourself with the user you have created during the initial setup of the application.

Mattermost Login

8 . Once logged in click on the menu button, then on System Console to enter the configuration interface of Mattermost.

9 . Inside the general settings section, click on Configuration.

10 . Configure the Listen Address as

Mattermost Configuration

This prevents direct connections to Mattermost from other machines.

11 . Restart the Mattermost service:

systemctl restart mattermost.service

12 . Reload the Mattermost application in your browser. The basic configuration has been done now, you can start chatting:

Mattermost Chat

You may configure advanced settings, like email notifications and other customizations of your Mattermost application. For more information, refer to the official documentation.

Discover the Cloud That Makes Sense