Skip to main content

Deploy Mattermost on Ubuntu or Debian

Install Mattermost Server on Ubuntu or Debian from the signed Mattermost APT repository. The same .deb packages cover single-host installs and clustered deployments via tools like Packer.

Minimum requirements
  • Operating system: Ubuntu 20.04 / 22.04 / 24.04 LTS, or Debian (current stable). Other Debian-family distributions usually work but aren't tested by Mattermost.
  • Hardware: 1 vCPU and 2 GB RAM (supports up to ~1,000 users).
  • Database: PostgreSQL 14+.
  • Network: TCP 80/443 inbound (TLS), 8065 inbound (System Console), 10025 outbound (SMTP relay if used).

Step 1: Get a PostgreSQL database​

Mattermost requires PostgreSQL. Choose one of:

  • Install PostgreSQL locally on the same host. Follow the PostgreSQL installation documentation.
  • Use an external PostgreSQL server. Collect the connection credentials (hostname, port, database, username, password) before starting Step 2.
  • Use a managed database service (AWS RDS, Azure Database for PostgreSQL, etc.).

Step 2: Prepare the database​

Follow the database preparation instructions to create the Mattermost database, user, and grants.

Step 3: Add the Mattermost APT repository​

GPG key change

The GPG public key has changed. Either import the new public key or run the repository setup script in the next step (recommended). Existing installations should remove the old key before adding the new one:

For Ubuntu 22.04 LTS and 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

Run the repository setup script:

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

This configures the Mattermost APT repository, a PostgreSQL repository, an NGINX web server (used as a reverse proxy), and certbot for issuing and renewing SSL certificates.

Step 4: Install Mattermost Server​

Update your APT cache and any pending system packages:

sudo apt update

Install the latest Mattermost Server:

sudo apt install mattermost -y

Mattermost installs to /opt/mattermost. The package creates a mattermost user and group and a systemd unit file. The service is not enabled or started at this point.

systemd dependencies

The Mattermost package doesn't declare a database dependency in its systemd unit (the package is used for both single-host and external-database installs). If you installed PostgreSQL on the same host, add the following to the [Unit] section of /lib/systemd/system/mattermost.service:

After=postgresql.service
BindsTo=postgresql.service

Step 5: Configure the server​

Copy the default configuration to the active config file with the right ownership and permissions:

sudo install -C -m 600 -o mattermost -g mattermost \
  /opt/mattermost/config/config.defaults.json \
  /opt/mattermost/config/config.json

Edit /opt/mattermost/config/config.json and set:

  • SqlSettings.DriverName: "postgres"
  • SqlSettings.DataSource: "postgres://mmuser:<mmuser-password>@<host>:5432/mattermost?sslmode=disable&connect_timeout=10" — replace each placeholder.
  • ServiceSettings.SiteURL: the public URL of your deployment (e.g., https://mattermost.example.com).
  • (Recommended) SupportSettings.SupportEmail: the email address users contact for help.
TLS mode for DataSource

The sslmode value depends on your database environment. The two relevant options are disable and require. Managed services such as AWS Lightsail require sslmode=require. Check your provider's documentation.

Start the server:

sudo systemctl start mattermost

Verify it's running:

curl http://localhost:8065

You should see the Mattermost HTML response. Enable the service on boot:

sudo systemctl enable mattermost.service

Step 6: Update Mattermost​

When a new release is published, update through APT:

sudo systemctl stop mattermost
sudo apt update && sudo apt upgrade
sudo systemctl start mattermost
Stop the server before upgrading

apt upgrade will replace the Mattermost binary while it's running. Stop the systemd service first to avoid corrupt state.

Remove Mattermost​

sudo systemctl stop mattermost
sudo apt remove --purge mattermost

This removes the package but leaves /opt/mattermost/data, /opt/mattermost/logs, /opt/mattermost/plugins, and /opt/mattermost/config in place. Back these up before deleting if you may need to restore.

Next steps​