Operating System CentOS

How to Install Mattermost on AlmaLinux 9 or Rocky Linux 9

Set up a self-hosted Mattermost team chat server on AlmaLinux 9 or Rocky Linux 9 with PostgreSQL, a systemd service, SELinux contexts and firewalld rules.

Mattermost is an open-source, self-hosted team chat server with channels, direct messages, file sharing and integrations. This guide installs the current Mattermost Server release on AlmaLinux 9 or Rocky Linux 9 (the same steps apply to CentOS Stream 9 and RHEL 9) with a PostgreSQL database, a systemd service, SELinux left in enforcing mode and firewalld opened for the web port. At the end you have a working server on port 8065 that is ready to be placed behind a TLS reverse proxy.

CentOS 7 reached end of life on 30 June 2024 and cannot run current Mattermost at all: from version 12.0 the server binary needs glibc 2.34 or later, so RHEL 7 and 8 and their derivatives are limited to version 11.11 or earlier. Mattermost supports RHEL 9, CentOS Stream 9 and Oracle Linux 9 or newer, and its RHEL guide also names Rocky Linux 9 and AlmaLinux 9.

Requirements

  • A 64-bit AlmaLinux 9 or Rocky Linux 9 server. Mattermost lists 1 vCPU and 2 GB of RAM as enough for up to 1,000 users.
  • A user with sudo rights.
  • PostgreSQL 15 or later. MariaDB is not supported, and MySQL support is deprecated since Mattermost 11, so use PostgreSQL for a new installation.
  • A DNS name such as chat.example.com that points to the server, if you want to serve the site over HTTPS.

On the RHEL family Mattermost is installed from the official tarball. There is no dnf repository for it; the package repository Mattermost publishes is APT-only, for Ubuntu and Debian.

Step 1: Install PostgreSQL

The default postgresql package in the 9 family is version 13, which is too old. Newer versions are provided as AppStream module streams. List them and enable one that is 15 or higher:

sudo dnf update -y
sudo dnf module list postgresql
sudo dnf module enable -y postgresql:16
sudo dnf install -y postgresql-server glibc-langpack-en

Initialise the data directory, then start the service and enable it at boot:

sudo postgresql-setup --initdb
sudo systemctl enable --now postgresql
psql --version

Step 2: Create the database and user

Open a PostgreSQL shell as the postgres system user:

sudo -u postgres psql

Run the statements from the Mattermost documentation. Replace mmuser-password with a strong password of your own:

CREATE DATABASE mattermost WITH ENCODING 'UTF8' LC_COLLATE='en_US.UTF-8' LC_CTYPE='en_US.UTF-8' TEMPLATE=template0;
SET password_encryption = 'scram-sha-256';
CREATE USER mmuser WITH PASSWORD 'mmuser-password';
GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser;
ALTER DATABASE mattermost OWNER TO mmuser;
\c mattermost
ALTER SCHEMA public OWNER TO mmuser;
GRANT USAGE, CREATE ON SCHEMA public TO mmuser;
\q

If CREATE DATABASE fails with invalid LC_COLLATE locale name, the en_US.UTF-8 locale is missing: install glibc-langpack-en, restart PostgreSQL and run the statement again.

Mattermost connects over TCP to localhost with a password. A freshly initialised cluster on the RHEL family uses ident authentication for local TCP connections, which rejects that. Open the client authentication file:

sudo vi /var/lib/pgsql/data/pg_hba.conf

Change the method on the two host lines for 127.0.0.1/32 and ::1/128 to scram-sha-256:

host    all             all             127.0.0.1/32            scram-sha-256
host    all             all             ::1/128                 scram-sha-256

Reload PostgreSQL and test the login. You should get a mattermost=> prompt after typing the password; leave it with \q.

sudo systemctl reload postgresql
psql -h localhost -U mmuser -d mattermost

Step 3: Download and unpack Mattermost

Download the tarball from the Mattermost release server. The address has the form https://releases.mattermost.com/<version>/mattermost-<version>-linux-amd64.tar.gz; replace amd64 with arm64 on ARM hardware. The example uses 12.0.2. Check the Mattermost deployment page for the current version number, or for the current Extended Support Release if you prefer fewer upgrades.

sudo dnf install -y wget tar
cd /tmp
wget https://releases.mattermost.com/12.0.2/mattermost-12.0.2-linux-amd64.tar.gz

Extract it to /opt, create the data directory and a dedicated system user, and hand the tree to that user:

tar -xvzf mattermost*.gz
sudo mv mattermost /opt
sudo mkdir /opt/mattermost/data
sudo useradd --system --user-group mattermost
sudo chown -R mattermost:mattermost /opt/mattermost
sudo chmod -R g+w /opt/mattermost

Step 4: Create the systemd service

Create the unit file in /etc/systemd/system, the directory for units you manage yourself:

sudo vi /etc/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

Load the new unit:

sudo systemctl daemon-reload

Step 5: Configure Mattermost

Keep a copy of the shipped configuration, then edit the live file:

sudo cp /opt/mattermost/config/config.json /opt/mattermost/config/config.defaults.json
sudo vi /opt/mattermost/config/config.json

Set these values:

  • SqlSettings.DriverName: "postgres"
  • SqlSettings.DataSource: "postgres://mmuser:mmuser-password@localhost:5432/mattermost?sslmode=disable&connect_timeout=10" with your own password
  • ServiceSettings.SiteURL: the address users will open, for example "https://chat.example.com"
  • SupportSettings.SupportEmail: the address users should write to for help (recommended)

The file contains the database password, so make sure it stays owned by mattermost and is not world-readable:

sudo chown mattermost:mattermost /opt/mattermost/config/config.json
sudo chmod 600 /opt/mattermost/config/config.json

Step 6: Set SELinux contexts and open the firewall

AlmaLinux and Rocky Linux run SELinux in enforcing mode. Install the management tools and label the Mattermost binaries and port as the Mattermost documentation describes:

sudo dnf install -y policycoreutils-python-utils
sudo semanage fcontext -a -t bin_t "/opt/mattermost/bin(/.*)?"
sudo restorecon -RF /opt/mattermost/bin
sudo semanage port -a -t http_port_t -p tcp 8065

Run ls -Z /opt/mattermost. Only if the files show the type default_t, label the tree as well:

sudo semanage fcontext -a -t httpd_sys_content_t "/opt/mattermost(/.*)?"
sudo restorecon -R /opt/mattermost

Open port 8065 for the first test. Once a reverse proxy is in place you only need the http and https services.

sudo firewall-cmd --permanent --add-port=8065/tcp
sudo firewall-cmd --reload
sudo firewall-cmd --list-all

Step 7: Start Mattermost and create the first account

sudo systemctl start mattermost
curl http://localhost:8065
sudo systemctl enable mattermost.service

The curl command should print the HTML of the Mattermost page. Open http://203.0.113.10:8065 in a browser, using your server's address, and create the first account. That account becomes the system administrator.

If the service does not start, look at the log and at recent SELinux denials:

sudo systemctl status mattermost
sudo journalctl -u mattermost -n 50
sudo ausearch -m avc -ts recent

Do not switch SELinux to permissive mode on a production server to make an error go away. Fix the denial that ausearch reports instead.

Step 8: Put it behind HTTPS

Port 8065 serves plain HTTP. For real use, install NGINX as a reverse proxy with a TLS certificate for chat.example.com, proxy to http://localhost:8065 with WebSocket upgrade headers, and then change the firewall so only the web ports are public:

sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --permanent --remove-port=8065/tcp
sudo firewall-cmd --reload

Make sure SiteURL matches the public HTTPS address. The Mattermost deployment guide for RHEL links to a tested NGINX configuration and lists the extra ports for the Calls plugin (8443 over UDP and TCP).

Upgrading a tarball installation

Tarball installations are upgraded by hand. In outline: download and extract the new release to a temporary directory, stop the service with sudo systemctl stop mattermost, back up the database and copy /opt/mattermost aside, remove the old program files while keeping config, logs, plugins, client/plugins and data, copy the new files in, restore ownership with sudo chown -R mattermost:mattermost /opt/mattermost and start the service. The exact commands, including the long find expression that removes old files safely, are in the Mattermost upgrade guide. Read the upgrade notes for every version you skip.

Frequently asked questions

Can I use MariaDB or MySQL instead of PostgreSQL?

MariaDB has never been a supported database for Mattermost. MySQL 8.0 still works, but its support has been deprecated since Mattermost 11, so a new server should start on PostgreSQL to avoid a database migration later.

Should I install the latest release or the Extended Support Release?

Monthly releases bring new features and need frequent upgrades. An Extended Support Release receives security and bug fixes for a longer period and suits servers that you want to touch rarely. Both are downloaded from the same release server; only the version number in the URL differs.

Why does Mattermost run on port 8065 rather than 80 or 443?

The service runs as the unprivileged mattermost user, which cannot bind ports below 1024 by default. Terminating TLS in a reverse proxy and forwarding to 8065 is the usual arrangement and keeps certificate handling out of the application.

Where are uploaded files stored?

With the default local file storage they are written to /opt/mattermost/data. Include that directory, /opt/mattermost/config/config.json and a PostgreSQL dump of the mattermost database in your backups.

Share story:

Continue reading other guides on How VPS.