How To Install Mattermost Server on Debian 12 (Bookworm)

Welcome to this detailed guide on how to deploy Mattermost Server on Debian 12 (Bookworm). But before that, we need to know what is Mattermost.

Mattermost is an open-source collaboration software preferred by most technical and operational teams around the world. It is designed for a large number of concurrent users that work in environments with complex nation-state-level security and trust requirements. With Mattermost, you can easily establish communication between individuals using chat, voice and video calls. Some of the popular competitors to Mattermost are MS Teams and Slack.

What makes it preferred over other tools are the cool features it brings. These include:

• It is fully extensible and offers support for third Party Integrations
• The Incident resolution which makes resolving incidents quick and time-saving
• Supports document storage
• It is cross-platform, it can run on Windows, Android, Linux, and Mac operating systems
• Supports data Import and export
• Offers Drag & Drop features
• It offers application and network performance monitoring.
• Provides workflow management and orchestration.
• It provides alerts/Notifications

Installation Requirements

For this guide, you need to have:

• Debian 12 (Bookworm) with 1 vCPU/cores with 2GB RAM (support up to 1,000 users)
• Database server: PostgreSQL v11+
• User with sudo privileges.
• A Fully Qualified Domain Name(Optional for SSL certs)

Follow the below steps to deploy the Mattermost Server on Debian 12 (Bookworm).

1) Install PostgreSQL Database Server

The first thing we need to do is to ensure that a database server is set up for Mattermost. The recommended database server for Mattermost is PostgreSQL v11 and above.

To install it, use the commands:

sudo apt update
sudo apt install postgresql postgresql-contrib -y

Verify if the service is running:

$ systemctl status postgresql
● postgresql.service - PostgreSQL RDBMS
     Loaded: loaded (/lib/systemd/system/postgresql.service; enabled; preset: enabled)
     Active: active (exited) since Mon 2023-08-14 03:49:03 EDT; 29s ago
   Main PID: 63061 (code=exited, status=0/SUCCESS)
        CPU: 1ms

Ensure the service is enabled to run on system boot

sudo systemctl enable postgresql

Access the shell with the command:

sudo -u postgres psql

Create a database and user for Matermost:

CREATE USER mmuser WITH PASSWORD 'P@ssw0rd!';
CREATE DATABASE mattermost OWNER mmuser;
\q

2) Install Mattermost Server

Once the database server has been installed and configured, we need to download the Mattermost Server. Get the latest available version from the official Mattermost downloads page.

Download the latest available Tarball. This can be done by exporting the required version:

VER=9.4.1

Pull the archive using:

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

Once downloaded, extract the archive:

tar -xvzf mattermost*.tar.gz

Move the file to the /opt directory:

sudo mv mattermost /opt

The next thing is to create a storage directory to persist the data.

sudo mkdir /opt/mattermost/data

Create a dedicated user and group for Mattermost:

sudo useradd --system --user-group mattermost

Set the required permissions for the directory:

sudo chown -R mattermost:mattermost /opt/mattermost
sudo chmod -R g+w /opt/mattermost

Now we will make configurations for Mattermost:

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

In the file, add your database creds as shown under the Sqlsettings section. Remember to provide the created user, password and database name.

"SqlSettings": {
    "DriverName": "postgres",
    "DataSource": "postgres://mmuser:P@ssw0rd!@localhost/mattermost?sslmode=disable\u0026connect_timeout=10\u0026binary_parameters=yes",
    "DataSourceReplicas": [],
    "DataSourceSearchReplicas": [],
    "MaxIdleConns": 20,
    "ConnMaxLifetimeMilliseconds": 3600000,
    "ConnMaxIdleTimeMilliseconds": 300000,
    "MaxOpenConns": 300,
    "Trace": false,
    "AtRestEncryptKey": "",
    "QueryTimeout": 30,
    "DisableDatabaseSearch": false,
.........
  },

Save the made changes and test if all is okay:

cd /opt/mattermost
sudo -u mattermost bin/mattermost

Sample Output:

.......
{"timestamp":"2023-08-14 04:02:16.315 -04:00","level":"info","msg":"rtc: server is listening on udp 127.0.0.1:8443","caller":"app/plugin_api.go:973","plugin_id":"com.mattermost.calls","origin":"main.(*logger).Info log.go:95"}
{"timestamp":"2023-08-14 04:02:16.316 -04:00","level":"info","msg":"rtc: server is listening on udp 192.168.200.56:8443","caller":"app/plugin_api.go:973","plugin_id":"com.mattermost.calls","origin":"main.(*logger).Info log.go:95"}
{"timestamp":"2023-08-14 04:02:16.317 -04:00","level":"info","msg":"rtc: server is listening on udp 192.168.200.175:8443","caller":"app/plugin_api.go:973","plugin_id":"com.mattermost.calls","origin":"main.(*logger).Info log.go:95"}
{"timestamp":"2023-08-14 04:02:16.317 -04:00","level":"info","msg":"rtc: server is listening on udp 10.244.2.1:8443","caller":"app/plugin_api.go:973","plugin_id":"com.mattermost.calls","origin":"main.(*logger).Info log.go:95"}
{"timestamp":"2023-08-14 04:02:16.318 -04:00","level":"info","msg":"Listening TCP on 0.0.0.0:8443","caller":"app/plugin_api.go:973","plugin_id":"com.mattermost.calls","origin":"main.(*logger).Info log.go:95"}
{"timestamp":"2023-08-14 04:02:16.334 -04:00","level":"info","msg":"Starting Server...","caller":"app/server.go:912"}
{"timestamp":"2023-08-14 04:02:16.334 -04:00","level":"info","msg":"Server is listening on [::]:8065","caller":"app/server.go:988","address":"[::]:8065"}

This shows that Mattermost is working and listening to connections on port 8065(the default port). To stop the service, issue Ctrl+C then run the command:

sudo killall -9 mattermost

3) Create Mattermost Systemd unit

To manage the Mattermost service using systemd, we need to create a service file.

cat <<EOF | sudo tee /lib/systemd/system/mattermost.service 
[Unit]
Description=Mattermost
After=network.target

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

[Install]
WantedBy=multi-user.target
EOF

Reload the systemd using the command:

sudo systemctl daemon-reload

Start and enable the service:

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

Check the status of the service:

$ systemctl status mattermost.service 
●mattermost.service - Mattermost
     Loaded: loaded (/lib/systemd/system/mattermost.service; enabled; preset: enabled)
     Active: active (running) since Mon 2023-08-14 04:07:42 EDT; 10s ago
   Main PID: 63819 (mattermost)
      Tasks: 26 (limit: 4623)
     Memory: 290.0M
        CPU: 6.237s
     CGroup: /system.slice/mattermost.service
             ├─63819 /opt/mattermost/bin/mattermost
             ├─63833 plugins/com.mattermost.nps/server/dist/plugin-linux-amd64
             ├─63843 plugins/com.mattermost.calls/server/dist/plugin-linux-amd64
             └─63849 plugins/playbooks/server/dist/plugin-linux-amd64

If you have a firewall enabled, allow the port through it:

sudo ufw allow 8065

4) Access the Mattermost Web Interface

Now that Mattermost has been installed and started, you can access its web interface using the URL http://IP_Address:8065 or http://domain_name:8065

You have the option of using a Desktop App or continuing with the web interface. Here, we will proceed with the web UI. Create a user account by providing the required details.

Set your organization name

Choose the tools you use in your environment.

You will be given a link to invite members to the team.

That is it! You will now have Mattermost ready for use.

5) Secure Mattermost with Let’s Encrypt

There are two ways of securing Mattermost with SSL certs. These are:

• Setting up TLS on the Mattermost server.
• Use a proxy such as NGINX and set up TLS on the proxy.

For this guide, we will use a proxy, which is recommended if you have more than 200 users for better performance. This method also provides standard HTTP request logs.

Install the Nginx proxy on Debian 12 using the command:

sudo apt install nginx -y

Once installed, configure a virtual hosts file:

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

In the file, add the below lines:

    server {
        listen       80 default_server;
        listen       [::]:80 default_server;
        server_name  mattermost.computingforgeeks.com;

        location / {
	proxy_pass http://localhost:8065/;
            index  index.html index.htm;
        }

        error_page 404 /404.html;
            location = /40x.html {
        }

        error_page 500 502 503 504 /50x.html;
            location = /50x.html {
        }
    }

Disable the default nginx site;

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

Save the file and restart nginx:

sudo systemctl restart nginx

Once a virtual host has been created, install the required tools to generate certs with Let’s Encrypt.

sudo apt install certbot python3-certbot-nginx

Issue the trusted SSL certs for the domain name captured in your virtual host file:

sudo certbot --nginx

Proceed as shown:

Saving debug log to /var/log/letsencrypt/letsencrypt.log
Enter email address (used for urgent renewal and security notices)
 (Enter 'c' to cancel): Enter a valid Email address here          

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please read the Terms of Service at
https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf. You must
agree in order to register with the ACME server. Do you agree?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: y

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Would you be willing, once your first certificate is successfully issued, to
share your email address with the Electronic Frontier Foundation, a founding
partner of the Let's Encrypt project and the non-profit organization that
develops Certbot? We'd like to send you email about our work encrypting the web,
EFF news, campaigns, and ways to support digital freedom.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: y
Account registered.

Which names would you like to activate HTTPS for?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1: mattermost.computingforgeeks.com
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Select the appropriate numbers separated by commas and/or spaces, or leave input
blank to select all options shown (Enter 'c' to cancel): 1

Requesting a certificate for mattermost.computingforgeeks.com
Performing the following challenges:
http-01 challenge for mattermost.computingforgeeks.com
Waiting for verification...
Cleaning up challenges
Deploying Certificate to VirtualHost /etc/nginx/conf.d/mattermost.conf
Redirecting all traffic on port 80 to ssl in /etc/nginx/conf.d/mattermost.conf

Successfully received certificate.
Certificate is saved at: a2enmod ssl
/etc/letsencrypt/live/mattermost.computingforgeeks.com/fullchain.pem
Key is saved at:         /etc/letsencrypt/live/mattermost.computingforgeeks.com/privkey.pem
This certificate expires on 2022-01-09.
These files will be updated when the certificate renews.
Certbot has set up a scheduled task to automatically renew this certificate in the background.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
If you like Certbot, please consider supporting our work by:
 * Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
 * Donating to EFF:                    https://eff.org/donate-le
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

You will have the SSL certs automatically added to your conf file. Allow HTTPS through the firewall:

sudo ufw allow 443

Restart the service:

sudo systemctl restart nginx

Now access the service via HTTPS using the URL https://domain_name

6) Install and Use Mattermost Desktop

Mattermost provides two ways of access. You can also install and use a desktop app. There are desktop apps for different operating systems as captured on the Mattermost desktop apps page. In this guide, I will show you how to download and install the app on Linux systems.

Use the commands to install the Mattermost desktop

• On Debian/Ubuntu

curl -o- https://deb.packages.mattermost.com/setup-repo.sh | sudo bash
sudo apt update && sudo apt  install mattermost-desktop -y

• On RHEL/CentOS/Rocky Linux, you need to download the latest RPM package.

Export the RPM version:

VER=5.4.0

Pull and install the RPM package:

##For 64-bit
wget https://releases.mattermost.com/desktop/$VER/mattermost-desktop-$VER-linux-x86_64.rpm
sudo rpm -u mattermost-desktop-$VER-linux-x86_64.rpm

##For 32-Bit
wget https://releases.mattermost.com/desktop/$VER/mattermost-desktop-$VER-linux-i686.rpm
sudo rpm -u mattermost-desktop-$VER-linux-i686.rpm

Once installed, launch the desktop app from the App menu;

Connect to your Mattermost server by providing the server URL (HTTPS recommended) and the display name

Login to the server.

Once connected, you will see this.

Voila!

We have successfully walked through how to deploy Mattermost Server on Debian 12 (Bookworm). I hope this was of great importance to you.

See more on our page:

• Install and Configure Mattermost on a Kubernetes Cluster
• How To Run Mattermost Server in Docker Containers
• Install Mattermost Server on CentOS 8|RHEL 8
• Install Mattermost Server on Ubuntu 22.04|20.04|18.04