How to Install Mattermost on Ubuntu

Technical writer

Servers

14.11.2024

Reading time: 8 min

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.

Technical Requirements

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:

For PostgreSQL 16: We'll provision a DBaaS with 1 CPU, 1 GB RAM, and 20 GB of disk space.
For Mattermost: We'll provision a server running Ubuntu with 2 CPUs, 2 GB RAM, and 60 GB of disk space.

We will also need to restrict access to the database. We will do it by setting up a private network in Hostman.

Environment Setup

Creating a Private Network

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.

Database

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.

Server for Mattermost

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.

Domain

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.

Installing Mattermost

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.

Installing the Service

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

Configuring Mattermost

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.

Starting Mattermost

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

Enabling Auto-Start

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.

Setting Up Nginx as a Reverse Proxy for Mattermost

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

Setting Up SSL with Let’s Encrypt:

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:

A listen directive for handling requests on port 443 (HTTPS)
SSL keys and configuration directives
A redirect from HTTP to 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.

Setting Up Firewall

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.

First Launch

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.

Conclusion

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.