Install Mattermost Server using the tarball
Minimum system requirements:
- Hardware: 1 vCPU/core with 2GB RAM (support for up to 1,000 users)
- Database: PostgreSQL v11+
- Application 80/443, TLS, TCP Inbound
- Administrator Console 8065, TLS, TCP Inbound
- SMTP port 10025, TCP/UDP Outbound
You can install the Mattermost Server on any 64-bit Linux system using the tarball. This is the most flexible installation method, but it comes with the highest effort, normally favored by advanced system administrators.
If you are running the Mattermost Server and database on a single system, we recommend the Mattermost Omnibus install method as this greatly reduces setup and ongoing maintenance, and uses the Mattermost PPA for updates. More modern installation methods such as the Mattermost Helm Chart or Kubernetes Operator are available and are highly recommended.
You need a PostgreSQL database. See the database preparation documentation for details on this prerequisite.
In a terminal window, ssh onto the system that will host the Mattermost Server.
wget, download the Mattermost Server release you want to install.
wget https://releases.mattermost.com/9.2.2/mattermost-9.2.2-linux-amd64.tar.gzCopied to clipboard
wget https://releases.mattermost.com/8.1.6/mattermost-8.1.6-linux-amd64.tar.gzCopied to clipboard
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
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
sudo useradd --system --user-group mattermost
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
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.
If you are installing the Mattermost server on the same system as your database, you may want to add both
BindsTo=postgresql.service to the
[Unit] section of the systemd unit file.
Before you start the Mattermost Server, you need to edit the configuration file. A default configuration file is located at
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:
"postgres". This is the default and recommended database for all Mattermost installations.
mattermostwith your database name.
"SiteURL": The domain name for the Mattermost application (e.g.
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.
Updating your Mattermost Server installation when using the tarball requires several manual steps. See the upgrade Mattermost Server documentation for details.
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
Depending on your configuration, there are several important folders in
/opt/mattermost to backup. These are
data. We strongly recommend you back up these locations before running the
You may also remove the Mattermost systemd unit file and the user/group created for running the application.
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
BindsTo=postgresql.service to the
Can I run Mattermost without a proxy?
Yes. However, like NGINX, in place, 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
We don’t recommend deploying Mattermost on a single server unless you have fewer than 200 users.
We recommend the Mattermost Omnibus install method over the tarball if you are running the Mattermost Server and database a single system as this greatly reduces setup and ongoing maintenance.