Install Mattermost on Ubuntu/Debian
Mattermost being great alternative to Slack has been open source for long time. While slack charges you $5 per user per month, you can host unlimited user on self hosted version of Mattermost on cloud server for as little as $5 per month.
I already had discussed installation of Rocket.chat few years ago, but since then Rocket.chat has evolved from open source to closed source more or less. With many restriction on free version of rocket chat, it is time to try on new way to chat and collaborate. For those who don’t know about Slack or Mattermost, it is a package for team collaboration.
Requirements:
Mattermost recommend 4GB of RAM and 2 vCPU to start with, however you can install it on server with as little as 2GB of RAM. Later you can scale the cloud as per your need and number of concurrent users.
Start with Ubuntu 24.04 or Debian 12 on cloud server, however you can also install it on RHEL distribution like Almalinux or Rockylinux. This will be covered in separate article.
Although you can instal
Preparation:
Start with connecting to server using SSH client like Putty, Bitvise if you are on Windows. Otherwise run the following command to connect to server from Mac or Linux terminal.
Installing Postgres
Mattermost suggest you to install postgres 14+. We will install latest postgres at the time of writing which is postgres 18.
# Import the repository signing key:
sudo apt install curl ca-certificates
sudo install -d /usr/share/postgresql-common/pgdg
sudo curl -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc --fail https://www.postgresql.org/media/keys/ACCC4CF8.asc
# Create the repository configuration file:
. /etc/os-release
sudo sh -c "echo 'deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt $VERSION_CODENAME-pgdg main' > /etc/apt/sources.list.d/pgdg.list"
# Update the package lists:
sudo apt update
Install PostgreSQL: You can replace “18” by higher or lower version if you want.
sudo apt install postgresql-18
You will be asked for confirmation, answer Y
After this operation, 191 MB of additional disk space will be used.
Do you want to continue? [Y/n] Y
Access PostgreSQL by running:
sudo -u postgres psql
Next create the database
CREATE DATABASE mattermost WITH ENCODING 'UTF8' LC_COLLATE='en_US.UTF-8' LC_CTYPE='en_US.UTF-8' TEMPLATE=template0;
Now create the Mattermost user with a secure password:
CREATE USER mmuser WITH PASSWORD 'your-strong-password';
I would suggest that you generate Alpanumeric character of atleast 24 characters and avoid special character. However if you want to use special character then you should convert the special character to ASCII while pasting the password in config. If you fail
Now grant database access to the user:
GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser;
Now since we are using PostgreSQL v15.x or later, additional grants are required:
ALTER DATABASE mattermost OWNER TO mmuser;
ALTER SCHEMA public OWNER TO mmuser;
GRANT USAGE, CREATE ON SCHEMA public TO mmuser;
Exit
\q
Next you have to allow connecttion from Mattermost to PostgreSQL
For that edit pg_hba.conf to allow local connections
sudo nano /etc/postgresql/*/main/pg_hba.conf
Add or modify this line to allow password authentication:
local all mmuser md5
Something like the following
# Database administrative login by Unix domain socket
local all postgres peer
# Mattermost user - MUST come before the general "local all all" rule
local all mmuser md5
# TYPE DATABASE USER ADDRESS METHOD
local all all peer
host all all 127.0.0.1/32 scram-sha-256
host all all ::1/128 scram-sha-256
local replication all peer
host replication all 127.0.0.1/32 scram-sha-256
host replication all ::1/128 scram-sha-256
Enable and restart the PostgreSQL to apply the configuration changes:
sudo systemctl enable postgresql
sudo systemctl restart postgresql
Add the Mattermost Server PPA repository
For Ubuntu Jammy – 22.04 LTS and Ubuntu Noble – 24.04 LTS:
sudo rm /usr/share/keyrings/mattermost-archive-keyring.gpg
curl -sL -o- https://deb.packages.mattermost.com/pubkey.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/mattermost-archive-keyring.gpg > /dev/null
Run this command to add the Mattermost Server repositories:
curl -o- https://deb.packages.mattermost.com/repo-setup.sh | sudo bash -s mattermost
Install Mattermost server
Let’s update the server once againnad thenwe install the mattermost
sudo apt update
sudo apt install mattermost -y
The installation path is /opt/mattermost.
Since in this article our foucs is local installation we need to update the systemd unit, which was created when we installed mattermost but not set to active.
nano /lib/systemd/system/mattermost.service
Here you will see
[Unit]
Description=Mattermost
After=network-online.target
Update it to look like
[Unit]
Description=Mattermost
After=postgresql.service
BindsTo=postgresql.service
Configure the server
In this step you need to edit the configuration file. A sample configuration file is located at /opt/mattermost/config/config.defaults.json.
Let’s rename this configuration file with correct permissions, then we edit it.
sudo install -C -m 600 -o mattermost -g mattermost /opt/mattermost/config/config.defaults.json /opt/mattermost/config/config.json
nano /opt/mattermost/config/config.json
Under ServiceSettings, set "SiteURL": "https://example.com",
Under SqlSettings, DriverName is set to "postgres" by default. Just make sure that. No change required here.
Further Under SqlSettings, set DataSource to "postgres://mmuser:[email protected]:5432/mattermost?sslmode=disable\u0026connect_timeout=10\u0026binary_parameters=yes"
Replace your-strong-password with your password created during postgress database installation.
Let’s reload the daemon first
systemctl daemon-reload
Now it’s time to install
sudo systemctl start mattermost
sudo systemctl enable mattermost.service
Enabling SSL
It’s time to install SSL for the domain so that you can access the domain without adding trailing port.
We will start it by installing nginx.
Let’s install the nginx
apt install nginx -y
Now you have to create the nginx configuration
sudo nano /etc/nginx/sites-available/mattermost.conf
Paste the following content, replace the example.com with your hostname
# Upstream configuration for Mattermost
upstream backend {
server 127.0.0.1:8065;
keepalive 32;
}
# Proxy cache configuration
proxy_cache_path /var/cache/nginx/mattermost levels=1:2 keys_zone=mattermost_cache:10m max_size=3g inactive=120m use_temp_path=off;
# HTTP server - redirect to HTTPS
server {
listen 80;
server_name example.com;
# Redirect all HTTP traffic to HTTPS
return 301 https://$server_name$request_uri;
}
# HTTPS server
server {
listen 443 ssl http2;
server_name example.com;
# SSL certificate configuration
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
# SSL configuration
ssl_session_timeout 1d;
ssl_session_cache shared:MozSSL:10m;
ssl_session_tickets off;
# Modern SSL configuration
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off;
# WebSocket location
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;
}
# Main location
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;
}
}
Let’s create a symbolic link
sudo ln -s /etc/nginx/sites-available/mattermost.conf /etc/nginx/sites-enabled/mattermost.conf
Now it’s time to restart the nginx
sudo systemctl restart nginx
Next step is to install the certbot to get free SSL from Letsencrypt
sudo apt install python3-certbot-nginx
Run the following command to get the SSL for your domain from Letsencrypt
root@workspace:~# sudo certbot --nginx -d workspace.augustushealthcare.com
Saving debug log to /var/log/letsencrypt/letsencrypt.log
Enter email address (used for urgent renewal and security notices)
(Enter 'c' to cancel): [email protected]
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please read the Terms of Service at
https://letsencrypt.org/documents/LE-SA-v1.5-February-24-2025.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
Restart the nginx to load the SSL file
sudo systemctl restart nginx
Also restart the Mattermost
sudo systemctl restart mattermost
Issue
You are seeing nginx default page
Run the following command to confirm that
root@workspace:/var/cache/nginx# ls -la /etc/nginx/sites-enabled/
total 8
drwxr-xr-x 2 root root 4096 Nov 8 10:16 .
drwxr-xr-x 8 root root 4096 Nov 8 09:56 ..
lrwxrwxrwx 1 root root 34 Nov 8 09:46 default -> /etc/nginx/sites-available/default
lrwxrwxrwx 1 root root 42 Nov 8 10:16 mattermost.conf -> /etc/nginx/sites-available/mattermost.conf
If you are seeing default -> /etc/nginx/sites-available/default
then run the following commands, it will fix the issue.
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl restart nginx
Conclusion
Self hosting mattermost is not that difficult as it may appear. With right guidance it can be installed easily by any person.
Leave a Reply
Want to join the discussion?Feel free to contribute!