How to Install Mattermost on Debian 12

Mattermost is an open-source alternative to Slack and Microsoft Teams. It allows you to self-host online chat and offers many features like file sharing, search, automation, and numerous third-party integrations.

Mattermost is a collaboration platform designed as an internal chat for organizations and companies. It combines messaging systems, automation, integrations, and security for critical workflows.

This guide'll show you how to install Mattermost on a Debian 12 server. You'll install Mattermost with PostgreSQL and Nginx, and you'll also secure Mattermost with SSL certificates.

Prerequisites

To start with this guide, make sure you have the following:

  • A Debian 12 server
  • A non-root user with administrator privileges
  • A domain name is ready and pointed to the server IP address

Installing dependencies

Before installing Mattermost, you need to install dependencies for it. This includes the PostgreSQL database server, Nginx web server, and Certbot.

First, run the following command to update your Debian package index.

sudo apt update

update repo

Now install dependencies such as PostgreSQL, Nginx, Certbot, Gnupg, and curl using the 'apt' command below. Enter 'Y' to confirm the installation.

sudo apt install postgresql postgresql-contrib nginx certbot gnupg curl

install deps

Once the installation is complete, check the PostgreSQL service status with the 'systemctl' command. You'll see that PostgreSQL is running on your system.

sudo systemctl is-enabled postgresql
sudo systemctl status PostgreSQL

check postgresql

Lastly, check the Nginx service status using the command below. The Nginx service should be up and running on your Debian system.

sudo systemctl is-enabled nginx
sudo systemctl status nginx

check nginx status

Setting up PostgreSQL user and database

After dependencies are installed, you'll be creating a new database and user for Mattermost. For this, you'll be utilizing the PostgreSQL shell 'psql', which is installed by default when installing a PostgreSQL server.

Log in to PostgreSQL with the 'psql' command below.

sudo -u postgres psql

Now run the following queries to create a new database and user 'mattermost' with the password 'password'.

CREATE DATABASE mattermost;
CREATE USER mmuser WITH PASSWORD 'password';
GRANT ALL ON DATABASE mattermost TO mmuser;
ALTER DATABASE mattermost OWNER TO mmuser;
GRANT USAGE, CREATE ON SCHEMA PUBLIC TO mmuser;

create datbase and user

Next, check the list of databases and users in your PostgreSQL server with the following:

\l
\du

In the following, you can see the database and user 'mattermost' is created.

Type 'quit' to exit from the 'psql' shell.

listing database and user

With the new PostgreSQL user and database created, you'll be verify your PostgreSQL user to ensure it can log in to the PostgreSQL server.

Now run the 'psql' command below to log in to the PostgreSQL server with the user 'mattermost'. Enter your password when prompted.

sudo -u postgres psql --host=localhost --dbname=mattermost --username=mmuser --password

Once logged in, check your connection with the following query:

\conninfo

You'll see the connection status to the PostgreSQL like the following:

connection info

Installing Mattermost

At this point, your server is ready for Mattermost installation. Now you'll download the Mattermost source code, set up the installation directory, configure Mattermost with PostgreSQL, set up the Mattermost domain name, and then set up proper permission and ownership of the Mattermost installation directory.

Before downloading Mattermost, add the new system user 'mattermost' with the following:

sudo useradd --system --user-group mattermost

Now run the following 'wget' command to download Mattermost and extract it using the 'tar' command below. The Mattermost server will be available in the 'mattermost' directory.

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

Next, move the 'mattermost' directory to the '/opt' with the following. So the Mattermost installation directory will be available at the '/opt/mattermost'.

mv mattermost /opt/

And then create a new data directory '/opt/mattermost/data'. This will be used for storing user data.

sudo mkdir -p /opt/mattermost/data

Next, open the default Mattermost configuration '/opt/mattermost/config/config.json' with the 'nano' editor.

sudo nano /opt/mattermost/config/config.json

Change the 'SiteURL' with your domain name such as 'https://mattermost.howtoforge.local'.

"ServiceSettings": {
"SiteURL": "https://mattermost.howtoforge.local",

Within the 'SqlSettings' and 'DataSource' sections, change the database credentials with your details like the following:

"SqlSettings": {
"DriverName": "postgres",
"DataSource": "postgres://mattermost:password@localhost/mattermost?sslmode=disable\u0026connect_timeout=10\u0026binary_parameters=yes",

Save the file and exit the editor.

Lastly, run the command below to change the ownership of the '/opt/mattermost' directory to the user 'mattermost'. Also, make sure that group 'mattermost' can write to the '/opt/mattermost' directory.

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

Creating systemd service for Mattermost

In this section, you'll be creating a new systemd service file for Mattermost. With this, Mattermost will be running in the background and you can easily manage the Mattermost process with the 'systemctl' utility.

Create a new systemd service file '/etc/systemd/system/mattermost.service' using the 'nano' editor.

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

Insert the following configuration into the file.

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

[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

Save the file and exit the editor.

Now run the 'systemctl' command below to reload the systemd manager.

sudo systemctl daemon-reload

Lastly, you can now start, enable, and verify the 'mattermost' service with the following command.

sudo systemctl enable --now mattermost
sudo systemctl status mattermost

As seen in the following, the 'mattermost' service is running and enabled.

mattermost service

Configuring Nginx as a reverse proxy

At this point, Mattermost is running on your Debian 12 server. As for this section, you'll be generating SSL certificates from Letsencrypt, and then creating a new Nginx server block that will be used as a reverse proxy for Mattermost.

Before configuring Nginx, run the command below to stop the Nginx service and generate SSL certificates for Mattermost. Make sure to change the domain name and email address with your information.

sudo systemctl stop nginx
sudo certbot --certonly --standalone --agree-tos --no-eff-email --staple-ocsp --preferred-challenges http -m [email protected] -d mattermost.howtoforge.local

After the process is finished, your SSL/ certificates will be available in the '/etc/letsencrypt/live/mattermost.howtoforge.local' directory.

Next, open the default Nginx configuration '/etc/nginx/nginx.conf' with the 'nano' editor.

sudo nano /etc/nginx/nginx.conf

Add the following configuration before the line '/etc/nginx/nginx.conf'.

 server_names_hash_bucket_size 64;
include /etc/nginx/conf.d/*.conf;

Save and exit the file.

Now create a new Nginx server block configuration '/etc/nginx/sites-available/mattermost' using the 'nano' editor.

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

Insert the configuration below and make sure to change the 'server_name' option with your domain name. Also, be sure to adjust the path of SSL certificates.

upstream backend {
server 127.0.0.1:8065;
keepalive 32;
}

server {
listen 80;
server_name mattermost.howtoforge.local;
return 301 https://$server_name$request_uri;
}

server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name mattermost.howtoforge.local;

http2_push_preload on; # Enable HTTP/2 Server Push

ssl_certificate /etc/letsencrypt/live/mattermost.howtoforge.local/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/mattermost.howtoforge.local/privkey.pem;
ssl_session_timeout 1d;

# Enable TLS versions (TLSv1.3 is required upcoming HTTP/3 QUIC).
ssl_protocols TLSv1.2 TLSv1.3;

# Enable TLSv1.3's 0-RTT. Use $ssl_early_data when reverse proxying to
# prevent replay attacks.
#
# @see: https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_early_data
ssl_early_data on;

ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384';
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:50m;
# HSTS (ngx_http_headers_module is required) (15768000 seconds = six months)
add_header Strict-Transport-Security max-age=15768000;
# OCSP Stapling ---
# fetch OCSP records from URL in ssl_certificate and cache them
ssl_stapling on;
ssl_stapling_verify on;

add_header X-Early-Data $tls1_3_early_data;

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 $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 60s;
send_timeout 300s;
lingering_timeout 5s;
proxy_connect_timeout 90s;
proxy_send_timeout 300s;
proxy_read_timeout 90s;
proxy_http_version 1.1;
proxy_pass http://backend;
}

location / {
client_max_body_size 100M;
proxy_set_header Connection "";
proxy_set_header Host $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_http_version 1.1;
proxy_pass http://backend;
}
}

# This block is useful for debugging TLS v1.3. Please feel free to remove this
# and use the '$ssl_early_data' variable exposed by NGINX directly should you
# wish to do so.
map $ssl_early_data $tls1_3_early_data {
"~." $ssl_early_data;
default "";
}

When finished, save the file and exit the editor.

Now activate the Nginx server block for mattermost and verify your Nginx syntax. If you've correct syntax, you'll see an output 'syntax is ok - test is successful'.

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

Lastly, run the `systemctl` command below to restart the Nginx service and apply your changes. With this, Mattermost will be running under Nginx reverse proxy.

sudo systemctl restart nginx

setup nginx reverse proxy

Creating the first workspace in Mattermost

Open your web browser and visit https://mattermost.howtoforge.local. If your installation is successful, you'll be asked to create a new admin for Mattermost.

Enter the new admin user, email, and password, then click 'Create Account'.

create admin account

Input your organization name and click 'Continue'.

name organization

For integration with GitHub, Gitlab, Jira, or/and Zoom, select as needed. And then click 'Continue' again.

integration

Click 'Finish setup' to complete the configuration.

finishe setup

After the process is complete, you'll see the Mattermost dashboard like the following:

installation complete

Conclusion

Congratulations! You've completed the installation of Mattermost on the Debian 12 server. You've Mattermost up and running with PostgreSQL as the database and Nginx as a reverse proxy. Lastly, you've also secured Mattermost with HTTPS through Certbot and Letsencrypt. For the next step, you may need to add an SMTP server to your Mattermost installation to allow email notifications. Additionally, you can also integrate Mattermost with third-party applications.

Share this page:

0 Comment(s)