Install Mattermost on RHEL#

Available on all plans

Self-hosted deployments

Minimum system requirements:

  • Operating System: Enterprise Linux 7+, Oracle Linux 6+, Oracle Linux 7+
  • Hardware: 1 vCPU/core with 2GB RAM (support for up to 1,000 users)
  • Database: PostgreSQL v12+
  • Network:
    • Application 80/443, TLS, TCP Inbound
    • Administrator Console 8065, TLS, TCP Inbound
    • SMTP port 10025, TCP/UDP Outbound

Note

You need a PostgreSQL database. See the database preparation documentation for details on this prerequisite.

A Mattermost deployment includes 4 steps: download, install, setup, and update.

Download the latest Mattermost Server tarball#

In a terminal window, ssh onto the system that will host the Mattermost Server.

Using wget, download the Mattermost Server release you want to install.

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

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

If you are looking for an older release, Enterprise and Team Edition releases can be found in our version archive documentation.

Install#

Ahead of installing the Mattermost Server, it’s good practice to update all your repositories and, where required, update existing packages by running the following commands:

sudo dnf update
sudo dnf upgrade

After any updates, and any system reboots, are complete, install the Mattermost Server.

Install the Mattermost Server by extracting the tarball, creating users and groups, and setting file/folder permissions.

First extract the tarball:

tar -xvzf mattermost*.gz

Now move the entire folder to the /opt directory (or whatever path you require):

sudo mv mattermost /opt

Note

If you choose a custom path, ensure this alternate path is used in all steps that follow.

By default the Mattermost Server uses /opt/mattermost/data as the folder for files. This can be changed in the System Console during setup (even using alternative storage such as S3). Create the default storage folder:

sudo mkdir /opt/mattermost/data

Now set up a user and group called mattermost:

sudo useradd --system --user-group mattermost

Note

If you choose a custom user and group name, ensure it is used in all the steps that follow.

Set the file and folder permissions for your installation:

sudo chown -R mattermost:mattermost /opt/mattermost

Give the mattermost group write permissions to the application folder:

sudo chmod -R g+w /opt/mattermost

You will now have the latest Mattermost Server version installed on your system. Starting and stopping the Mattermost Server is done using systemd. Create the systemd unit file:

sudo touch /lib/systemd/system/mattermost.service

As root, edit the systemd unit file to add the following lines:

[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

Save the file and reload systemd using sudo systemctl daemon-reload. Mattermost Server is now installed and is ready for setup.

Note

If you are installing the Mattermost server on the same system as your database, you may want to add both After=postgresql.service and BindsTo=postgresql.service to the [Unit] section of the systemd unit file.

Setup#

Before you start the Mattermost Server, you need to edit the configuration file. A default configuration file is located at /opt/mattermost/config/config.json.

We recommend taking a backup of this default config ahead of making changes:

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

Configure the following properties in this file:

  • Set DriverName to "postgres". This is the default and recommended database for all Mattermost installations.

  • Set DataSource to "postgres://mmuser:<mmuser-password>@<host-name-or-IP>:5432/mattermost?sslmode=disable&connect_timeout=10" replacing mmuser, <mmuser-password>, <host-name-or-IP>, and mattermost with your database name.

  • Set your "SiteURL": The domain name for the Mattermost application (e.g. https://mattermost.example.com).

After modifying the config.json configuration file, you can now start the Mattermost server:

sudo systemctl start mattermost

Verify that Mattermost is running: curl http://localhost:8065. You should see the HTML that’s returned by the Mattermost Server.

The final step, depending on your requirements, is to run sudo systemctl enable mattermost.service so that Mattermost will start on system boot.

Modify SELinux settings#

When deploying Mattermost from RHEL9, which has SELinux running with enforceing mode enabled by default, additional configuration is required the SELinux policy is being enforced and denies access based on SELinux policy rules.

First, ensure that SELinux is enabled and in enforcing mode by running the sestatus command. If it’s enforcing, you’ll need to configure it properly.

Set the correct contexts for /opt/mattermost#

SELinux enforces security contexts for files and directories. To label your Mattermost directory as safe, you’ll need to set an appropriate SELinux context.

  1. Check current context by running ls -Z /opt/mattermost. When you see something like drwxr-xr-x. root root unconfined_u:object_r:default_t:s0 mattermost returned, the default_t indicates that SELinux doesn’t know what this directory is for.

  2. Set a safe context by assigning a SELinux type that’s compatible with web services or applications by running sudo semanage fcontext -a -t httpd_sys_content_t "/opt/mattermost(/.*)?". A common one is httpd_sys_content_t, used for serving files. Ensure you match the directory and its contents recursively. Run the sudo restorecon -R /opt/mattermost to apply the changes.

Allow Mattermost to bind to ports#

When Mattermost needs specific ports (e.g., 8065), ensure that SELinux allows it by allowing Mattermost to bind to ports. Run the sudo semanage port -l | grep 8065 command, and if the port’s not listed, you’ll need to add it by running sudo semanage port -a -t http_port_t -p tcp 8065, replacing the 8065 with the required port.

Handle custom policies#

If Mattermost requires actions that SELinux blocks, you’ll need to generate a custom policy.

  1. Check for SELinux denials first in the logs by running sudo ausearch -m avc -ts recent, or by checking the audit log: sudo cat /var/log/audit/audit.log | grep denied.

  2. If needed, generate a policy module by installing audit2allow to generate policies automatically.

sudo yum install -y policycoreutils-python-utils
sudo grep mattermost /var/log/audit/audit.log | audit2allow -M mattermost_policy
sudo semodule -i mattermost_policy.pp

Test the configuration#

Restart Mattermost to confirm the configuation works as expected by running sudo systemctl restart mattermost. In the case of failures, revisit the logs to identify other SELinux-related issues.

Tip

Need Mattermost working quickly for testing purposes? You can change SELinux to permissive mode by running the sudo setenforce 0. command where policies aren’t enforced, only logged. This command changes the SELinux mode to “permissive”. While in permissive mode, policies aren’t enforced, and violations are logged instead of being blocked. This can be helpful for debugging and troubleshooting issues related to SELinux policies. Ensure you re-enable enforcing mode once context is working as needed by running the sudo setenforce 1 command.

See the following SELinux resources for additional details:

Updates#

Updating your Mattermost Server installation when using the tarball requires several manual steps. See the upgrade Mattermost Server documentation for details.

Remove Mattermost#

If you wish to remove the Mattermost Server for any reason, you must stop the Mattermost Server, back up all important files, and then run this command:

sudo rm /opt/mattermost

Note

Depending on your configuration, there are several important folders in /opt/mattermost to backup. These are config, logs, plugins, client/plugins, and data. We strongly recommend you back up these locations before running the rm command.

You may also remove the Mattermost systemd unit file and the user/group created for running the application.

Frequently asked questions#

Why doesn’t Mattermost start at system boot?#

To have the Mattermost Server start at system boot, the systemd until file needs to be enabled. Run the following command:

sudo systemctl enable mattermost.service

Why does Mattermost fail to start at system boot?#

If your database is on the same system as your Mattermost Server, we recommend editing the default /lib/systemd/system/mattermost.service systemd unit file to add After=postgresql.service and BindsTo=postgresql.service to the [Unit] section.

Can I run Mattermost without a proxy?#

Yes. Mattermost binds to 443 instead of 8065. The Mattermost binary requires the correct permissions to do that binding. You must activate the CAP_NET_BIND_SERVICE capability to allow the new Mattermost binary to bind to ports lower than 1024 by running the following command:

sudo setcap cap_net_bind_service=+ep ./mattermost/bin/mattermost

Note

  • We highly recommend using a proxy in front of Mattermost server for up to 200 concurrent users. If you have fewer than 200 concurrent users, you can set up TLS. If you’re exceeding 200 concurrent users, you’ll need a proxy, such as NGINX, in front of Mattermost to manage the traffic.