Install Mattermost Server on Ubuntu#

Available on all plans

Self-hosted deployments

Minimum system requirements:

  • Operating System: 20.04 LTS, 22.04 LTS, 24.04 LTS
  • 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

You can install the Mattermost Server using our .deb signed packages using the Mattermost PPA (Personal Package Archive). Using the Mattermost Personal Package Archive (PPA) not only provides the quickest way to install a Mattermost Server, but also provides automatic updates. This install method is used for both single and clustered installations.

Tip

  • 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.

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

A Mattermost deployment includes 4 steps: add the PPA repository, install, setup, and update.

Add the Mattermost Server PPA repository#

Important

The GPG public key has changed. You can import the new public key or run the automatic Mattermost PPA repository setup script provided below. Depending on your setup, additional steps may also be required, particularly for installations that didn’t rely on the repository setup script. We recommend deleting the old key from /etc/apt/trusted.gpg.d before adding the apt repository.

  • For Ubuntu Focal - 20.04 LTS:

    sudo apt-key del A1B31D46F0F3A10B02CF2D44F8F2C31744774B28

    curl -sL -o- https://deb.packages.mattermost.com/pubkey.gpg | gpg --dearmor | sudo apt-key add

  • For Ubuntu Jammy - 22.04 LTS and Ubuntu Noble - 24.04 LTS:

    sudo rm /usr/share/keyrings/mattermost-archive-keyring.gpg

    curl -sL -o- https://deb.packages.mattermost.com/pubkey.gpg |  gpg --dearmor | sudo tee /usr/share/keyrings/mattermost-archive-keyring.gpg > /dev/null

In a terminal window, run the following repository setup command to add the Mattermost Server repositories:

curl -o- https://deb.packages.mattermost.com/repo-setup.sh | sudo bash -s mattermost

This command configures the repositories needed for a PostgreSQL database, configures an NGINX web server to act as a proxy, configures certbot to issue and renew the SSL certificate, and configures the Mattermost Omnibus repository so that you can run the install command.

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 command:

sudo apt update

After any updates, and any system reboots, are complete, installing the Mattermost Server is now a single command:

sudo apt install mattermost -y

You now have the latest Mattermost Server version installed on your system.

The installation path is /opt/mattermost. The package will have added a user and group named mattermost. The required systemd unit file has also been created but will not be set to active.

Note

Since the signed package from the Mattermost repository is used for mulitple installation types, we don’t add any dependencies in the systemd unit file. 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 sample configuration file is located at /opt/mattermost/config/config.defaults.json.

Rename this configuration file with correct permissions:

sudo install -C -m 600 -o mattermost -g mattermost /opt/mattermost/config/config.defaults.json /opt/mattermost/config/config.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 "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.

Note

The value of the sslmode property in the DataSource configuration is entirely dependent on your native environment. Please consult the native environment setup documentation for guidance on its value. The available options for sslmode are disable or require. For example, if you are using Amazon Lightsail as your data source, you must set sslmode to require to successfully connect to the database.

Updates#

When a new Mattermost version is released, run: sudo apt update && sudo apt upgrade to download and update your Mattermost instance.

Note

When you run the sudo apt upgrade command, mattermost-server will be updated along with any other packages. We strongly recommend you stop the Mattermost Server before running the apt command using sudo systemctl stop mattermost-server.

Remove Mattermost#

If you wish to remove the Mattermost Server for any reason, you can run this command:

sudo apt remove --purge mattermost

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.