How to Install Mattermost on Ubuntu 24.04 LTS (Step-by-Step Guide)

We cover the latest stable release: Mattermost 11.5.1 (March 2026). All commands are tested on Ubuntu 24.04 LTS (Noble Numbat) and are fully compatible with Ubuntu 22.04 LTS as well.

Who is this for? System administrators and DevOps engineers who want full control over their team’s communication data, need to avoid cloud vendor lock-in, or operate in environments with strict data residency or compliance requirements (HIPAA, GDPR, FedRAMP).

Prerequisites

Before you begin, make sure you have the following ready:

Important: Mattermost dropped MySQL support in version 10.0. PostgreSQL is the only supported database going forward.

Step 1: Update the System

SSH into your server and update all packages before installing anything:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget gnupg2 ca-certificates lsb-release

If there were kernel updates, reboot before continuing:

sudo reboot

Step 2: Install PostgreSQL

Install PostgreSQL from the Ubuntu default repositories:

sudo apt install -y postgresql postgresql-contrib

Start the service and enable it to launch on boot:

sudo systemctl start postgresql
sudo systemctl enable postgresql

Verify it is running:

sudo systemctl status postgresql

You should see active (running) in the output.

Create the Mattermost Database and User

Switch to the postgres system user and open the psql shell:

sudo -u postgres psql

Run the following SQL — replace StrongPassword123! with a secure, unique password:

CREATE USER mmuser WITH PASSWORD 'StrongPassword123!';
CREATE DATABASE mattermost WITH OWNER mmuser ENCODING 'UTF8' LOCALE 'en_US.UTF-8' TEMPLATE template0;
GRANT ALL PRIVILEGES ON DATABASE mattermost TO mmuser;
\q

Optionally verify the connection:

psql -U mmuser -d mattermost -h localhost -W

Type the password when prompted. If you get a mattermost=# prompt, the database is ready. Type \q to exit.

Step 3: Install Mattermost Server

There are two methods. The PPA method is recommended for production as it supports automatic updates.

Method A: Install from the Official Mattermost PPA (Recommended)

Add the Mattermost repository to your system:

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

Install Mattermost:

sudo apt install mattermost -y

This installs Mattermost to /opt/mattermost. Future updates are handled with:

sudo systemctl stop mattermost
sudo apt update && sudo apt upgrade mattermost
sudo systemctl start mattermost

Method B: Install from Tarball (Manual)

Use this method if you need a specific version or prefer manual control:

# Download the latest release
wget https://releases.mattermost.com/11.5.1/mattermost-11.5.1-linux-amd64.tar.gz

# Extract to /opt
sudo tar -xvzf mattermost-11.5.1-linux-amd64.tar.gz -C /opt/

# Create the file storage directory
sudo mkdir -p /opt/mattermost/data

# Create a dedicated system user and group
sudo useradd --system --user-group mattermost

# Set ownership and permissions
sudo chown -R mattermost:mattermost /opt/mattermost
sudo chmod -R g+w /opt/mattermost

Step 4: Configure Mattermost

Open the main configuration file:

sudo nano /opt/mattermost/config/config.json

Find the SqlSettings section and update the database connection string:

"SqlSettings": {
    "DriverName": "postgres",
    "DataSource": "postgres://mmuser:StrongPassword123!@localhost:5432/mattermost?sslmode=disable&connect_timeout=10",
    ...
}

Find the ServiceSettings section and set your site URL:

"ServiceSettings": {
    "SiteURL": "https://chat.yourdomain.com",
    "ListenAddress": ":8065",
    ...
}

Save and exit: Ctrl+X, then Y, then Enter.

Tip: If you don’t have a domain yet, set SiteURL to http://YOUR_SERVER_IP:8065 temporarily. You can update it later from the System Console.

Step 5: Create a systemd Service

Create a systemd unit file to manage the Mattermost process:

sudo nano /etc/systemd/system/mattermost.service

Paste the following content:

[Unit]
Description=Mattermost
After=network.target
After=postgresql.service
BindsTo=postgresql.service

[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

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable mattermost
sudo systemctl start mattermost

Check the status:

sudo systemctl status mattermost

You should see active (running). You can also confirm Mattermost is listening on port 8065:

curl http://localhost:8065/api/v4/system/ping

A response of {"status":"OK"} confirms the server is up.

Step 6: Install and Configure Nginx (Reverse Proxy)

Nginx sits in front of Mattermost, handling port 80/443, SSL termination, and WebSocket proxying.

Install Nginx:

sudo apt install -y nginx
sudo systemctl enable nginx
sudo systemctl start nginx

Create the Mattermost virtual host config:

sudo nano /etc/nginx/sites-available/mattermost

Paste the following — replace chat.yourdomain.com with your actual domain or server IP:

upstream backend {
   server localhost:8065;
   keepalive 32;
}

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=mattermost_cache:10m max_size=3g inactive=120m use_temp_path=off;

server {
   listen 80;
   server_name chat.yourdomain.com;
   return 301 https://$host$request_uri;
}

server {
   listen 443 ssl http2;
   server_name chat.yourdomain.com;

   ssl_certificate /etc/letsencrypt/live/chat.yourdomain.com/fullchain.pem;
   ssl_certificate_key /etc/letsencrypt/live/chat.yourdomain.com/privkey.pem;
   ssl_session_timeout 1d;
   ssl_protocols TLSv1.2 TLSv1.3;
   ssl_prefer_server_ciphers on;
   ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;

   # WebSocket support
   location ~ /api/v[0-9]+/(users/)?websocket$ {
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
       client_max_body_size 50M;
       proxy_set_header Host $http_host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $scheme;
       proxy_set_header X-Frame-Options SAMEORIGIN;
       proxy_buffers 256 16k;
       proxy_buffer_size 16k;
       client_body_timeout 60s;
       send_timeout 300s;
       lingering_timeout 5s;
       proxy_connect_timeout 90;
       proxy_send_timeout 300;
       proxy_read_timeout 90s;
       proxy_pass http://backend;
   }

   location / {
       client_max_body_size 50M;
       proxy_set_header Connection "";
       proxy_set_header Host $http_host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $scheme;
       proxy_set_header X-Frame-Options SAMEORIGIN;
       proxy_buffers 256 16k;
       proxy_buffer_size 16k;
       proxy_read_timeout 600s;
       proxy_cache mattermost_cache;
       proxy_cache_revalidate on;
       proxy_cache_min_uses 2;
       proxy_cache_use_stale timeout;
       proxy_cache_lock on;
       proxy_http_version 1.1;
       proxy_pass http://backend;
   }
}

Enable the site and test the configuration:

sudo ln -s /etc/nginx/sites-available/mattermost /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Step 7: Install SSL with Let’s Encrypt

If your server is publicly accessible with a domain name, get a free SSL certificate:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d chat.yourdomain.com

Follow the prompts — enter your email, agree to terms, and choose whether to redirect HTTP to HTTPS (recommended: yes). Certbot automatically updates your Nginx config.

Set up automatic renewal:

sudo crontab -e

Add this line:

0 12 * * * /usr/bin/certbot renew --quiet

Alternative: Self-Signed Certificate (for internal/private networks)

If your Mattermost is on a private network with no public domain:

sudo openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
  -keyout /etc/ssl/private/mattermost.key \
  -out /etc/ssl/certs/mattermost.crt \
  -subj "/CN=chat.local"

Update the Nginx config to point to these files instead of the Let’s Encrypt paths.

Step 8: Configure the Firewall

Open only the ports you need:

sudo ufw allow 22/tcp     # SSH
sudo ufw allow 80/tcp     # HTTP (redirects to HTTPS)
sudo ufw allow 443/tcp    # HTTPS
sudo ufw enable
sudo ufw status

Port 8065 does not need to be open publicly — Nginx proxies requests to it internally.

Step 9: Initial Mattermost Setup

Open your browser and navigate to your server’s URL:

https://chat.yourdomain.com

You will see the Mattermost setup wizard. Complete the following steps:

• Step 1 — Create Admin Account: Enter a username, email address, and a strong password for the system administrator account.
• Step 2 — Create Your Team: Enter a team name and choose a URL handle (e.g., mycompany). This creates your first workspace.
• Step 3 — Invite Team Members: You can skip this step and invite users later from the System Console.
• Step 4 — You’re in: The main Mattermost channel view loads. You’re ready.

Step 10: Important System Console Settings

Log in as admin, click the grid icon (top left), and go to System Console to configure the following:

SMTP Email (for notifications and account verification):

Go to Environment > SMTP. Enter your SMTP server credentials. For quick testing you can use Gmail SMTP or any transactional email service (SendGrid, Mailgun, Amazon SES).

Restrict Open Registration:

Go to Authentication > Email and disable “Enable Open Server” if you don’t want anyone with the URL to create an account. Use invite links instead.

File Storage Limits:

Go to Environment > File Storage. Set Maximum File Size to your preference (default is 50 MB). For large engineering teams sharing logs or build artifacts, consider increasing this.

Push Notifications (Mobile Apps):

Go to Environment > Push Notification Server and set the server to https://push.mattermost.com to enable mobile push notifications for the official Mattermost iOS and Android apps.

Enable Multi-Factor Authentication:

Go to Authentication > MFA and enable MFA. For security-critical environments, also enable “Enforce MFA” to require it for all users.

Installing a Mattermost Enterprise License

The free Team Edition (self-hosted) covers all core messaging features with unlimited users and message history. If your organization needs any of the following, you will need a Professional or Enterprise license:

• LDAP / Active Directory sync
• SAML 2.0 Single Sign-On
• Advanced compliance exports and audit logs
• Group-based LDAP channel management
• Custom data retention policies
• 24/7 enterprise support SLA

To install a license file:

• Go to System Console > Edition and License
• Click Upload License File
• Select your .mattermost-license file

Useful Management Commands

Keep these handy for day-to-day server management:

# Check service status
sudo systemctl status mattermost

# Restart the service
sudo systemctl restart mattermost

# Follow live logs
sudo journalctl -u mattermost -f

# View last 100 log lines
sudo journalctl -u mattermost -n 100

# Backup the database
sudo -u postgres pg_dump mattermost | gzip > mm_backup_$(date +%Y%m%d).sql.gz

# Backup file storage
sudo tar -czf mm_data_$(date +%Y%m%d).tar.gz /opt/mattermost/data/

# Update Mattermost (PPA method)
sudo systemctl stop mattermost
sudo apt update && sudo apt upgrade mattermost
sudo systemctl start mattermost

Troubleshooting Common Issues

Issue: Mattermost service fails to start

Check the logs immediately:

sudo journalctl -u mattermost --since "2 minutes ago"

The most common cause is a wrong database connection string in config.json. Double-check the password, hostname, and database name in the DataSource field.

Issue: 502 Bad Gateway from Nginx

Mattermost is not running or is not listening on port 8065. Check:

sudo systemctl status mattermost
sudo ss -tlnp | grep 8065
curl http://localhost:8065/api/v4/system/ping

Issue: File uploads fail

Verify directory permissions:

sudo chown -R mattermost:mattermost /opt/mattermost/data
sudo chmod -R 700 /opt/mattermost/data

Also check that client_max_body_size in your Nginx config matches or exceeds the Mattermost file size limit.

Issue: WebSocket connection errors in the browser

Confirm your Nginx config includes the WebSocket proxy block (the location ~ /api/v[0-9]+/(users/)?websocket$ block). Without it, real-time updates and notifications will fail.

Issue: Push notifications not received on mobile

If your server is behind a firewall or in a restricted network environment, it may not be able to reach push.mattermost.com. In that case, deploy the open-source Mattermost Push Proxy on your own infrastructure and configure Mattermost to point to it.

Post-Installation Security Checklist

• Enforce MFA for all users in System Console
• Disable SSH password authentication — use key-based auth only
• Block port 8065 from public access in your firewall (Nginx handles it)
• Block port 5432 (PostgreSQL) externally — localhost only
• Set up automated daily database backups with offsite copy
• Install and configure fail2ban to block brute-force login attempts
• Keep Mattermost updated — subscribe to Mattermost Security Updates
• Review /opt/mattermost/logs/ regularly
• Configure custom data retention policies under System Console if required

Frequently Asked Questions (FAQ)

Does this guide work on Ubuntu 22.04?

Yes. All commands in this guide are compatible with Ubuntu 22.04 LTS. Ubuntu 24.04 LTS is preferred for new installations as it has a longer support window (through 2029).

Can I install Mattermost with Docker instead?

Yes, Docker is the fastest way to evaluate Mattermost:

docker run --name mattermost-preview -d \
  --publish 8065:8065 \
  mattermost/mattermost-preview

However, Docker is not recommended for production deployments as it lacks native high-availability support and adds operational overhead. For production, use the PPA or tarball method as described in this guide.

How many users can a single server handle?

A server with 1 vCPU and 2 GB RAM supports up to 1,000 concurrent users. With 2 vCPUs and 4 GB RAM, you can comfortably support 5,000 users. Mattermost publishes detailed hardware sizing guides for teams up to 200,000 users using clustered deployments.

Does Mattermost still support MySQL?

No. MySQL support was officially removed in Mattermost version 10.0. PostgreSQL (version 12 or newer) is the only supported database. If you are migrating from an older MySQL-based Mattermost installation, you must migrate the data to PostgreSQL first.

How do I back up Mattermost?

Back up both the database and the file storage directory:

# Database
sudo -u postgres pg_dump mattermost | gzip > mm_db_$(date +%Y%m%d).sql.gz

# Files
sudo tar -czf mm_data_$(date +%Y%m%d).tar.gz /opt/mattermost/data/

Store backups offsite — on a separate server, object storage (S3-compatible), or cloud backup service.

How do I upgrade Mattermost to a newer version?

If installed via PPA:

sudo systemctl stop mattermost
sudo apt update && sudo apt upgrade mattermost
sudo systemctl start mattermost

Always take a full backup before upgrading. Review the release notes for any breaking changes, especially when jumping multiple major versions.

How do I add users to my Mattermost server?

There are three ways: send email invitations from System Console, share a team invite link (found under Team Settings), or connect Mattermost to your LDAP/Active Directory for automatic user provisioning (requires Professional or Enterprise license).

How do I integrate Mattermost with GitLab?

In GitLab, go to Admin Area > Settings > Integrations > Mattermost notifications. Enter your Mattermost server URL and a webhook URL generated from your Mattermost System Console under Integrations > Incoming Webhooks. You can then configure which GitLab events (pushes, MRs, pipelines, issues) post to which Mattermost channels.

Can Mattermost run without internet access (air-gapped)?

Yes. Mattermost is fully functional without internet access once installed. Disable the Enable Diagnostics and Error Reporting option in System Console to prevent any outbound telemetry. For mobile push notifications in an air-gapped environment, deploy the Mattermost Push Proxy internally.