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 v13+
- Network:
- Application 80/443, TLS, TCP Inbound
- Administrator Console 8065, TLS, TCP Inbound
- SMTP port 10025, TCP/UDP Outbound
You can deploy Mattermost Server using our rpm
signed packages available through the Mattermost Yum repository.
This Mattermost deployment includes the following steps: install PostgreSQL database, prepare the database, download the Mattermost server, install the server, set up the server, and update the server.
Step 1: Install PostgreSQL database or get database connection credentials¶
Install PostgreSQL locally on the same server by following the PostgreSQL installation documentation.
Use an external PostgreSQL database server. Ensure you have connection credentials, including hostname, port, database name, username, and password available.
Use a managed database service.
Step 2: Prepare the database¶
Follow the database preparation documentation to set up your PostgreSQL database for Mattermost.
Step 3: 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 using one of the following commands. Replace amd64
with the appropriate architecture (e.g., arm64
for ARM-based systems) in the link as needed.
wget https://releases.mattermost.com/10.11.1/mattermost-10.11.1-linux-amd64.tar.gz
wget https://releases.mattermost.com/10.11.1/mattermost-10.11.1-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.
Step 4: Install Mattermost server¶
Ahead of installing the Mattermost Server, we recommend updating 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 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
Create the default storage folder. 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):sudo mkdir /opt/mattermost/data
Note
If you choose a custom path, ensure this alternate path is used in all steps that follow.`
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/mattermostYou 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 at
/lib/systemd/system/mattermost.service
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.
Step 5: Set up the server¶
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:
Under
SqlSettings
, setDriverName
to"postgres"
. This is the default and recommended database for all Mattermost installations.Under
SqlSettings
, setDataSource
to"postgres://mmuser:<mmuser-password>@<host-name-or-IP>:5432/mattermost?sslmode=disable&connect_timeout=10"
replacingmmuser
,<mmuser-password>
,<host-name-or-IP>
andmattermost
with your database name.Under
ServiceSettings
, set"SiteURL"
: The domain name for the Mattermost application (e.g.https://mattermost.example.com
).
Note
We recommend configuring the Support Email under SupportSettings
, set "SupportEmail"
. This is the email address your users will contact when they need help.
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. If you don’t receive an error when starting Mattermost after the previous step, you are good to go. If you did receive an error, continue on.
Important
Modify SELinux settings: When deploying Mattermost from RHEL9, which has SELinux running with enforceing mode enabled by default, additional configuration is required.
SELinux is a security module that provides access control security policies. It’s enabled by default on RHEL and CentOS systems. SELinux can block access to files, directories, and ports, which can cause issues when starting Mattermost. To resolve these issues, you’ll need to set the appropriate SELinux contexts for the Mattermost binaries and directories, and allow Mattermost to bind to ports.
Ensure that SELinux is enabled and in enforcing mode by running the
sestatus
command. If it’senforcing
, you’ll need to configure it properly.Set bin contexts for
/opt/mattermost/bin
: SELinux enforces security contexts for binaries. To label the Mattermost binaries as safe, you’ll need to set them to the below SELinux context.sudo semanage fcontext -a -t bin_t "/opt/mattermost/bin(/.*)?" sudo restorecon -RF /opt/mattermost/bin
Now, try starting Mattermost again with
sudo systemctl start mattermost
If you don’t receive an error, verify that Mattermost is running: curl
http://localhost:8065
. You should see the HTML that’s returned by the Mattermost Server. You’re all set!If on starting Mattermost you receive an error, before moving on, check for the existence of a file in
/opt/mattermost/logs
- ifmattermost.log
exists in that directory, it’s more likely you’re dealing with a configuration issue inconfig.json
. Double check the previous steps before continuingTry different 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.Check current context by running
ls -Z /opt/mattermost
. When you see something likedrwxr-xr-x. root root unconfined_u:object_r:default_t:s0 mattermost
returned, thedefault_t
indicates that SELinux doesn’t know what this directory is for.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 ishttpd_sys_content_t
, used for serving files. Ensure you match the directory and its contents recursively. Run thesudo 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 runningsudo semanage port -a -t http_port_t -p tcp 8065
, replacing the8065
with the required port.Handle custom policies: If Mattermost requires actions that SELinux blocks, you’ll need to generate a custom policy.
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
.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.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:
Step 6: Update the server¶
Updating your Mattermost Server installation when using the tarball requires several manual steps. See the upgrade Mattermost Server documentation for details.
Remove Mattermost¶
To remove the Mattermost Server, 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.