How to install Mattermost on Ubuntu and Debian

Mattermost is designed as an internal chat tool for organizations and markets itself as an open-source alternative to Slack and Microsoft Teams. The new feature release offers integration with enterprise tools such as Office 365 and Active Directory and an improved end-user experience for search and session management. Mattermost provides various features including file sharing, one-on-one and group messaging, custom emojis, video calls, and more. Please see the following guides on how to install and configure Ubuntu Linux, how to install the Windows Subsystem for Linux (WSL) on Windows Server via Server Manager and PowerShell, and how to set up SELinux on a Linux server. You may also be interested in the following open-source projects how to install Mattermost on Ubuntu and Debian, and how to install and configure Jitsi on Ubuntu.

In this guide, I will show you how to install Mattermost on Ubuntu 20.04 and 18.04 and Debian 10 with PostgreSQL as the backend database server and Nginx as the webserver. 

Part 1: Update the system: Run from the terminal and type the following command to update the package database as the root user. For more information on why this is done, see how to configure the OpenSSH server. For the difference between these commands below, see differences between Linux system Update, Upgrade, and Dist-upgrade.

# apt-get update
# apt-get upgrade

After upgrading the server, the best practice is to have your server rebooted.

Part 2: Install PostgreSQL Database Server: Since we do not have a database yet, I will be installing the PostgreSQL as shown below.
– You can also use MySQL or MariaDB as a database backend.

sudo apt -y install postgresql postgresql-contrib

Note: The PostgreSQL server will be started automatically after installation. Log in to the postgres account.

sudo --login --user postgres

Start the PostgreSQL interactive terminal and create the Mattermost database/user ‘tester’. Note: I had to rerun this so I could provide a screenshot of the process for you guys 🙂

psql
CREATE DATABASE mattermost;
CREATE USER tester WITH PASSWORD 'What@Mattermost';
GRANT ALL PRIVILEGES ON DATABASE mattermost to tester;
\q

Please ensure to note this username and password because it will be used later to populate the SQL Settings. Else the service will not start.

Now that this step has been completed, kindly log out of the Postgres account.

Part 3: Create a system user and group: Create a new user and group that will run our Mattermost instance. We will name the user “mattermost“.

sudo useradd --system --user-group mattermost

Now the system account has been created, we can confirm this by running the command “id mattermost“. As we can see the ID is less than 1000 and this is a rule for determining a system account.

Part 4: Download and Install the Mattermost Server: At the time of writing this article, the latest stable version of Mattermost is version 5.23.1.

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

Once the download is complete extract the archive and move it to the /opt directory

christian@christian-VirtualBox:~$ tar xvf mattermost-5.23.1-linux-amd64.tar.gz

Next, move the extracted file to the /opt directory.

sudo mv mattermost /opt

Create the storage directory for files and images that users post on Mattermost.

Change the directory ownership and permission to the mattermost user

sudo chown -R mattermost:mattermost /opt/mattermost

Also give the write permission to the mattermost group by using the command below

sudo chmod -R g+w /opt/mattermost

Part 5: Configure Mattermost Server. Open the /opt/mattermost/config/config.json file, set the database driver to Postgres, and enter the database information.

sudo vim /opt/mattermost/config/config.json 

Scroll to where you have the sqlSetttings as shown below and apend “postgres” to the DriverName and postgres:/ to the Data Source

    "SqlSettings": {
        "DriverName": "postgres",
        "DataSource": "postgres://tester:What@Mattermost@localhost:5432/mattermost?sslmode=disable&connect_timeout=10",
        "DataSourceReplicas": [],

Note: If you do not set the SqlSettings correctly, you will run into this error. Job for mattermost service failed because the control process exited with error code.

Part 6: Configure Systemd Service. In order to run our Mattermost instance as a service we will create a mattermost.service unit file in the /etc/systemd/system/ directory. Open your text editor and create the following file:

sudo vim /etc/systemd/system/mattermost.service

Now populate the file with the following information below. By default, it is empty.

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

[Service]
Type=notify
ExecStart=/opt/mattermost/bin/mattermost
TimeoutStartSec=3600
Restart=always
RestartSec=10
WorkingDirectory=/opt/mattermost
User=mattermost
Group=mattermost
LimitNOFILE=49152

[Install]
WantedBy=multi-user.target

Make Systemd load the new unit. This will notify systemd that we have created a new unit file and start the Mattermost service with the following commands.

sudo systemctl daemon-reload

Next, we will have to start and enable the Mattermost service with the command below. Also if there are no errors, enable the Mattermost service to automatically start at boot time.

sudo systemctl start mattermost.service
sudo systemctl enable mattermost.service

Note: This service can only start correctly if the username and password created for Mattermost are entered correctly into the SqlSettings section of the PostgreeSQL database.

We can now check the service status with the command “systemctl status mattermost.service”.

If you have Curl installed, you can verify with the command below directly from the commandline that Mattermost is running.

curl http://localhost:8065

Part 7: Finish Mattermost Web configuration: Open your browser and navigate to Mattermost instance on 8065. You can use IP Address such as 192.168.178.34:8065. But since i am on the server, i would rater go with localhost:8065.

Now that the account has been created,, I will create another user called christian12 for test reasons. I will also proceed in creating a Team called Team-Test as shown below.

Click on the Finish button and you will be redirected to the Mattermost dashboard. Please login and you will be able to send a direct message to your team members.

Please use this article to complete the necessary configuration related to you. Below are some of the settings that need to be configured. I cannot describe all these in detail as they are self-explanatory.

In order to complete the system-related settings,
– Open the System Console and lick on the System Console link

http://localhost:8065/admin_console/about/license

Perform the changes you desire for you organisation on this admin panel. You can set the MFA, email, TLS and SMTP etc.

Note: When you make any change to the Mattermost server, please restart the Mattermost service for the changes to take effect.

sudo systemctl restart mattermost

Part 8: This step requires us to configure the Nginx proxy server.
– Note: This is only needed in a production environment. Please use a proxy server for greater security and performance of Mattermost.

– Use the command below to install Nginx.

sudo apt -y install nginx

– Create a new configuration file for Mattermost

sudo nano /etc/nginx/conf.d/mattermost.conf

Please add the configuration settings as shown below to the configuration file

upstream backend {
   server 192.168.178.34:8065;
   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;
   server_name    chat.example.com;

   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;
   }
}

Next, reload the Nginx service for changes to take effect

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

Note: When you make any change to the Mattermost server, please restart the Mattermost service for the changes to take effect.

sudo systemctl restart mattermost

I hope you found this blog post helpful. If you have any questions, please let me know in the comment session. I welcome you to subscribe to my YouTube Channel.