Mattermost is a messaging and collaboration platform that can be installed on self-hosted servers or in the cloud. It serves as an alternative to messengers like Slack and Rocket.Chat.
In this guide, we will review the Free plan, which includes unlimited message history and group calls (for more details on pricing plans, see the official website). Mattermost clients are available for mobile (iOS, Android) and desktop (Windows, Linux, Mac), and there’s also a browser-based version.
Only the Self-Hosted Mattermost version is available under the Free plan;
We will go through the installation on Ubuntu. Other installation methods (including a Docker image) are available in the official docs.
For 1,000 users, a minimum configuration of 1 CPU, 2 GB RAM, and PostgreSQL v11+ or MySQL 8.0.12+ is required.
We will use the following resources:
We will also need to restrict access to the database. We will do it by setting up a private network in Hostman.
To restrict database access, we can use Firewall, but in this setup, all services will be within the same network.
Important: Services must be located in the same region to operate within a single network.
We'll provision the database as a service with the following configuration: 1 CPU, 1 GB RAM, and 20 GB of disk space, hosted in Poland.
While creating the database, in the Network section, select the No external IP option and the network created in the previous step.
The default database is default_db
, and the user is gen_user
.
Next, we need to set up a server for Mattermost and Nginx. This server will run Ubuntu 22.04 and will be hosted in Poland.
For the configuration, we need at least 2 CPUs, 2 GB RAM, and 50 GB of disk space, so we will choose a close enough plan:
You can also select the exact parameters (2 CPUs, 2 GB RAM, 50 GB) by using the Custom tab, but it will be more expensive.
As with the PostgreSQL setup, select the previously created network in the Network step.
Create the server.
We will also need a domain to obtain a TLS certificate. In this guide, we will use example.com.
You can add your domain in the Domains → Add domain section in the Hostman control panel.
Ensure the domain is linked to the server. You can verify this in the Network section. If the domain is not listed next to the IP address, it can be added manually through the Set Up Reverse Zone option.
Now that the environment is ready, we can proceed with installing Mattermost. To begin, we’ll connect to the repository at deb.packages.mattermost.com/repo-setup.sh
:
curl -o- https://deb.packages.mattermost.com/repo-setup.sh | sudo bash -s mattermost
Here, the mattermost argument is passed to sudo bash -s mattermost
to add only the Mattermost repository. If no argument is provided, the script’s default all argument will add repositories for Mattermost, Nginx, PostgreSQL, and Certbot.
The Mattermost service will install to /opt/mattermost, with a mattermost user and group created automatically:
sudo apt update
sudo apt install mattermost -y
After installation, create a config.json
file with the necessary permissions, based on the config.defaults.json
file. Read and write access should be granted only to the owner (in this case, the mattermost user):
sudo install -C -m 600 -o mattermost -g mattermost /opt/mattermost/config/config.defaults.json /opt/mattermost/config/config.json
Open config.json
to fill in key parameters:
sudo nano /opt/mattermost/config/config.json
Set the following:
SiteURL
: Enter the created domain with the https protocol in the ServiceSettings
block, which will be linked with an SSL certificate later.
"ServiceSettings": {
"SiteURL": "https://example.com",
"WebsocketURL": ""
}
DriverName
: Ensure this is set to postgres
in the SqlSettings
block.
DataSource
: Provide the username
, password
, host
, and database name
in the connection link in the SqlSettings
block.
Other configurations are optional for the initial launch and can be modified later in the Mattermost administrative console.
Start the Mattermost service:
sudo systemctl start mattermost
To verify that Mattermost started successfully:
sudo systemctl status mattermost.service
And verify it is accessible on port 8065
.
If the site doesn’t open, check the firewall settings. You can also verify local access to port 8065
directly from the server:
curl -v localhost:8065
Finally, enable Mattermost to start automatically on boot:
sudo systemctl enable mattermost.service
With these steps, Mattermost should be up and running and ready for further configuration and usage.
We will set up Nginx as a reverse proxy to prevent direct access on port 8065
, which will be closed later via firewall.
Install Nginx:
sudo apt install nginx
Create the Nginx Configuration File:
sudo nano /etc/nginx/sites-available/mattermost
Nginx Configuration for Mattermost:
Add the following configuration, replacing example.com
with your actual domain name. This configuration proxies both HTTP and WebSocket protocols.
upstream backend {
server 127.0.0.1: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 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;
}
}
Create a symbolic link to enable the Mattermost configuration:
sudo ln -s /etc/nginx/sites-available/mattermost /etc/nginx/sites-enabled/mattermost
Remove the default configuration:
sudo rm -f /etc/nginx/sites-enabled/default
Restart the Nginx service to apply the changes:
sudo service nginx restart
Use Certbot to obtain an SSL certificate for your domain. Certbot will automatically configure Nginx for HTTPS.
sudo apt install python3-certbot-nginx && certbot
Certbot will prompt you to enter your email and domain name and then add the certificate to your domain.
After installing the certificate, Certbot will update the Nginx configuration file to include:
443
(HTTPS)With this setup complete, Mattermost should be accessible over HTTPS on your domain. Nginx will handle HTTP to HTTPS redirection, and secure connections will be established using the SSL certificate from Let’s Encrypt.
Now, go to your Mattermost server page in the Hostman control panel. Open the Network tab to add firewall rules.
We will allow incoming TCP
requests to ports 22
for SSH access, and 80
and 443
for TCP
.
To collect metrics on the server dashboard, port 10050
also needs to be open; the list of IP addresses that require access to this port can be found in /etc/zabbix/zabbix_agentd.conf
.
Now you can Mattermost at https://your_domain/
.
You can create an account and workspace directly in the browser.
After installation and on the first login, you may encounter an issue with WebSocket connectivity.
To solve it, check the configuration. You can do it in the System Console.
Out-of-the-box features include calls, playbooks, a plugin marketplace, and GitLab authentication. Additionally, Mattermost offers excellent documentation.
In this guide, we deployed the free self-hosted version of Mattermost on Hostman servers with a dedicated database accessible only from the internal network. Keep in mind that we allocated the server resources for a general scenario, so you may need additional resources. It’s advisable not to skip load testing! As a next step, I recommend connecting an S3 storage, also available on Hostman.