How to Install Mattermost on Ubuntu: Complete Step-by-Step Guide

Mattermost is a powerful, open-source messaging and team collaboration platform that gives organizations full control over their communication infrastructure. As a self-hosted alternative to Slack and Microsoft Teams, Mattermost offers enterprise-grade security, complete data ownership, and extensive customization — all without recurring SaaS subscription costs.

This comprehensive guide walks you through every step of installing and configuring Mattermost on an Ubuntu server, including PostgreSQL database setup, Nginx reverse proxy configuration, and SSL certificate integration.

Table of Contents

1. Prerequisites
2. Update Your System
3. Install Required Dependencies
4. Download and Install Mattermost
5. Set Up the PostgreSQL Database
6. Configure Mattermost
7. Create a Systemd Service
8. Configure Nginx as a Reverse Proxy
9. Secure Mattermost with SSL (HTTPS)
10. Final Verification

1. Prerequisites

Before you begin, make sure the following requirements are in place:

• A server running Ubuntu 20.04 or Ubuntu 22.04 LTS (Ubuntu 18.04 is end-of-life and not recommended for production)
• Sudo or root privileges on the server
• A domain name pointed to your server's IP address (strongly recommended for production deployments)
• Minimum hardware: 1 vCPU, 2 GB RAM, 10 GB disk space (for small teams); scale up for larger deployments

> Hosting Tip: For a smooth Mattermost deployment, consider a reliable VPS Hosting plan from AlexHost. With SSD storage, full root access, and guaranteed uptime, AlexHost VPS instances are ideal for self-hosted collaboration tools.

2. Update Your System

Always start by refreshing your package index and applying all pending security and system updates:

sudo apt update
sudo apt upgrade -y

Reboot the server if a kernel update was applied:

sudo reboot

3. Install Required Dependencies

Mattermost depends on three key components: PostgreSQL (database), Nginx (reverse proxy), and Certbot (SSL certificate management).

Install all required packages in one step:

sudo apt install -y postgresql postgresql-contrib
sudo apt install -y nginx
sudo apt install -y certbot python3-certbot-nginx

Verify that PostgreSQL and Nginx are running:

sudo systemctl status postgresql
sudo systemctl status nginx

Both services should show active (running).

4. Download and Install Mattermost

Step 1: Download the Latest Mattermost Release

Visit the official Mattermost releases page to find the latest stable version. Use wget to download it directly to your server:

wget https://releases.mattermost.com/9.5.0/mattermost-team-9.5.0-linux-amd64.tar.gz

> Note: Replace 9.5.0 with the latest available version number. Always use the most recent stable release for security patches and new features.

Step 2: Extract the Archive

tar -xvzf mattermost-team-9.5.0-linux-amd64.tar.gz

Step 3: Move Mattermost to the System Directory

Move the extracted folder to /opt, which is the standard Linux location for optional third-party software:

sudo mv mattermost /opt/mattermost

Step 4: Create a Dedicated Mattermost System User

Running Mattermost as a dedicated, unprivileged user is a critical security best practice:

sudo useradd -r -m -d /opt/mattermost -s /bin/false mattermost

Step 5: Create the Data Directory and Set Permissions

sudo mkdir -p /opt/mattermost/data
sudo chown -R mattermost:mattermost /opt/mattermost
sudo chmod -R 750 /opt/mattermost

5. Set Up the PostgreSQL Database

Mattermost requires a dedicated PostgreSQL database and user. Follow these steps carefully.

Step 1: Switch to the PostgreSQL System User

sudo -i -u postgres

Step 2: Open the PostgreSQL Interactive Shell

psql

Step 3: Create the Database, User, and Grant Privileges

Execute the following SQL commands one by one:

CREATE DATABASE mattermost_db;
CREATE USER mattermost WITH PASSWORD 'YourStrongPassword123!';
GRANT ALL PRIVILEGES ON DATABASE mattermost_db TO mattermost;

> Security Note: Replace YourStrongPassword123! with a strong, unique password. Use a password manager to generate and store it securely.

For PostgreSQL 15 and later, you also need to grant schema privileges:

c mattermost_db
GRANT ALL ON SCHEMA public TO mattermost;

Step 4: Exit the PostgreSQL Shell and Return to Your User

q
exit

6. Configure Mattermost

Step 1: Open the Mattermost Configuration File

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

Step 2: Update the Database Connection Settings

Locate the SqlSettings block and update it with your PostgreSQL credentials:

"SqlSettings": {
    "DriverName": "postgres",
    "DataSource": "postgres://mattermost:YourStrongPassword123!@localhost:5432/mattermost_db?sslmode=disable&connect_timeout=10",
    "DataSourceReplicas": [],
    "DataSourceSearchReplicas": [],
    "MaxIdleConns": 20,
    "ConnMaxLifetimeMilliseconds": 3600000,
    "MaxOpenConns": 300,
    "Trace": false,
    "AtRestEncryptKey": "",
    "QueryTimeout": 30
}

Step 3: Configure the Site URL

Find the ServiceSettings block and set your domain:

"ServiceSettings": {
    "SiteURL": "https://your_domain.com",
    ...
}

Replace your_domain.com with your actual domain name.

Step 4: Save and Exit

Press Ctrl+X, then Y, then Enter to save and close the file.

7. Create a Systemd Service

Running Mattermost as a systemd service ensures it starts automatically on boot and restarts on failure — essential for any production deployment.

Step 1: Create the Service File

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

Step 2: Add the Service Configuration

Paste the following content:

[Unit]
Description=Mattermost Team Messaging Server
After=network.target postgresql.service
Wants=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

Step 3: Enable and Start the Mattermost Service

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

Step 4: Verify the Service is Running

sudo systemctl status mattermost

You should see active (running). Mattermost listens on port 8065 by default.

8. Configure Nginx as a Reverse Proxy

Nginx acts as a reverse proxy, forwarding incoming HTTP/HTTPS traffic from port 80/443 to Mattermost's internal port 8065. This also enables WebSocket support, which Mattermost requires for real-time messaging.

Step 1: Create the Nginx Configuration File

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

Step 2: Add the Reverse Proxy Configuration

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 your_domain.com;

    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;
        proxy_read_timeout 600s;
        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_pass http://backend;
    }
}

Replace your_domain.com with your actual domain name.

Step 3: Enable the Site Configuration

sudo ln -s /etc/nginx/sites-available/mattermost /etc/nginx/sites-enabled/

Step 4: Test the Nginx Configuration for Syntax Errors

sudo nginx -t

Expected output:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Step 5: Restart Nginx

sudo systemctl restart nginx

9. Secure Mattermost with SSL (HTTPS)

Running Mattermost over HTTPS is mandatory for any production environment. It encrypts all communication between users and your server, protecting credentials and messages from interception.

> SSL Made Easy: AlexHost offers affordable SSL Certificates for all types of websites and applications. Alternatively, use the free Let's Encrypt method below.

Step 1: Obtain a Free SSL Certificate with Certbot

sudo certbot --nginx -d your_domain.com

Certbot will automatically:

• Verify domain ownership
• Issue a Let's Encrypt certificate
• Modify your Nginx configuration to enable HTTPS
• Set up automatic certificate renewal

Step 2: Verify Automatic Renewal

sudo certbot renew --dry-run

Step 3: Restart Nginx

sudo systemctl restart nginx

Your Mattermost instance is now accessible at https://your_domain.com.

10. Final Verification

Check All Services Are Running

sudo systemctl status postgresql
sudo systemctl status mattermost
sudo systemctl status nginx

Test Mattermost Directly on Port 8065

curl -I http://localhost:8065

You should receive an HTTP 200 OK or redirect response.

Complete the Web-Based Setup

1. Open your browser and navigate to https://your_domain.com
2. You will be greeted by the Mattermost setup wizard
3. Create your administrator account
4. Configure your first team and workspace
5. Invite team members and start collaborating

Troubleshooting Common Issues

Why Choose a Reliable Host for Mattermost?

The performance and reliability of your Mattermost instance depend heavily on the underlying infrastructure. For small to medium teams, a well-configured VPS is the ideal choice. For larger organizations with high message volumes, consider upgrading to a Dedicated Server for maximum performance, isolation, and control.

If you need a domain name for your Mattermost deployment, AlexHost offers competitive Domain Registration with full DNS management. And if you're running multiple services alongside Mattermost, Shared Web Hosting or a VPS with cPanel can simplify management with an intuitive control panel.

Summary

You have successfully installed and configured Mattermost on Ubuntu with:

• ✅ PostgreSQL as the backend database
• ✅ Nginx as a production-grade reverse proxy with WebSocket support
• ✅ Let's Encrypt SSL for encrypted HTTPS connections
• ✅ A systemd service for automatic startup and crash recovery
• ✅ Proper file permissions and a dedicated system user for security

Mattermost is now ready to serve as your team's private, self-hosted communication hub — fully under your control, with no data leaving your infrastructure.