🚀 Install and Run Self-hosted Mattermost Instance on Linux VPS

This article provides a comprehensive guide to install and run self-hosted Mattermost instance on Linux VPS (Ubuntu/Debian). This guide will set up Mattermost with PostgreSQL and NGINX as a reverse proxy with HTTPS.

What is Mattermost?

Mattermost is a self-hosted, open-source collaboration platform designed for secure team communication. It offers features similar to Slack or Microsoft Teams but gives organizations full control over data, deployment, and customization.

🧩 Key Features

• Team Messaging (channels, DMs, threads)
• File Sharing
• Voice and Video Calls (with plugins like Calls or Jitsi)
• Integrations & Webhooks (Jira, GitHub, CI/CD tools)
• Custom Commands and Bots
• Granular Permissions and Roles
• Mobile and Desktop Apps

🔒 Why Use Mattermost?

• ✅ Self-hosted: Run it on your own servers.
• ✅ Security-first: No third-party access to your messages.
• ✅ Open-source: Source code is public, extensible, and customizable.
• ✅ DevOps Friendly: Built with developers and tech teams in mind—great for integrating DevOps workflows.
• ✅ DevOps Friendly: Avoid potential vendor lock-in scenarios of cloud-based services.

🆚 Mattermost vs Slack

🏗️ Editions

• Team Edition: Free, core functionality, ideal for small teams.
• Enterprise Edition: Adds LDAP, compliance, HA, etc. for large orgs.
• Cloud: Hosted by Mattermost Inc. (optional).

🔧 Common Use Cases

• Developer teams
• Remote/distributed teams
• Government, finance, or healthcare orgs (privacy-focused)
• Incident response and DevOps collaboration

In short: Mattermost is a powerful, private alternative to Slack that puts you in control.

🧰 How to Install and Run Self-Hosted Mattermost Instance on Linux VPS

This guide assumes the following environment variables exist in your system. Attempting to perform the installation steps on a system that does not satisfy the conditions listed below can lead to unexpected behavior.

✅ Prerequisites

• VPS with Ubuntu 20.04+ (we recommend Ubuntu 24.04 LTS)
• Root (or sudo) access
• Domain name pointing to your server (e.g. chat.yourdomain.com)
• ~2GB RAM minimum (4GB+ recommended for production)
• Open ports: 80, 443 (HTTP/S)

To install and run self-hosted Mattermost instance on Linux VPS, please follow the steps provided below:

1. 🧱 Update System

   sudo apt update && sudo apt upgrade -y
   

2. 🐘 Install PostgreSQL

   Mattermost uses PostgreSQL for data storage.

   sudo apt install postgresql postgresql-contrib -y
   

   Configure PostgreSQL

   sudo -u postgres psql
   

   Inside the PostgreSQL prompt:

   CREATE DATABASE mattermost;
   CREATE USER mmuser WITH PASSWORD 'strongpassword';
   GRANT ALL PRIVILEGES ON DATABASE mattermost TO mmuser;
   \q
   

3. ✅ Create Mattermost User and Group

   sudo useradd --system --user-group --create-home --shell /sbin/nologin mattermost
   

   Explanation:

   • --system: Creates a system user (UID < 1000, no login by default).
   • --user-group: Creates a group with the same name (mattermost).
   • --create-home: Sets up a home directory (optional, but useful).
   • --shell /sbin/nologin: Prevents direct login access.

4. 📁 Download and Install Mattermost

   wget https://releases.mattermost.com/9.5.0/mattermost-9.5.0-linux-amd64.tar.gz
   tar -xvzf mattermost-9.5.0-linux-amd64.tar.gz
   sudo mv mattermost /opt
   sudo mkdir /opt/mattermost/data
   

   Give permissions:

   sudo chown -R mattermost:mattermost /opt/mattermost
   sudo chmod -R 770 /opt/mattermost
   

5. ⚙️ Configure Mattermost

   Edit the config:

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

   Change:

   • "DriverName": "postgres"
   • "DataSource": "postgres://mmuser:strongpassword@localhost:5432/mattermost?sslmode=disable"

   Also update "SiteURL": "https://chat.yourdomain.com"

   Save and exit.

6. 🔧 Create Systemd Service

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

   Paste the following:

   [Unit]
   Description=Mattermost
   After=network.target postgresql.service
   
   [Service]
   Type=simple
   User=mattermost
   Group=mattermost
   WorkingDirectory=/opt/mattermost
   ExecStart=/opt/mattermost/bin/mattermost
   Restart=always
   LimitNOFILE=49152
   
   [Install]
   WantedBy=multi-user.target
   

   Enable and start:

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

7. 🌐 Install and Configure NGINX

   sudo apt install nginx -y
   

   Create NGINX config

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

   Paste:

   server {
       listen 80;
       server_name chat.yourdomain.com;
   
       location / {
           proxy_pass http://localhost:8065;
           proxy_set_header Host $host;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "upgrade";
           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;
       }
   }
   

   Enable the config:

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

8. 🔒 Secure with Let’s Encrypt SSL

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

   Set up automatic renewal:

   sudo systemctl enable certbot.timer
   

9. 🧪 Test It Out

   Open your browser and visit:

   https://chat.yourdomain.com
   

   You should see the Mattermost setup page. Create the first admin user and you’re in!

10. 🧼 Harden and Monitor

    • Enable UFW or iptables firewall
    • Monitor Mattermost service: sudo journalctl -u mattermost
    • Backups: regularly back up /opt/mattermost and the PostgreSQL database
    • Consider setting up email notifications (SMTP) in config.json

📋 Summary

You now know how to install and run Self-hosted Mattermost instance on Linux VPS. Next, we will further configure our self-hosted Mattermost instance to apply important security and performance improvements and setup monitoring and logging of the Mattermost service. Let’s proceed.

Implement Best-Practices for Self-hosted Mattermost

Best-practices to Run self-hosted Mattermost instance include implementing the following additional security measures, optimizing performance, and configuring reliable monitoring and service logging.

🔐 Security Best Practices

1. Enable HTTPS Only

   • Redirect all HTTP traffic to HTTPS in your NGINX config.
   • Use HSTS to enforce SSL:

   add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
   

2. Secure Configuration Files

   • Set correct permissions on config.json and environment files:

   sudo chmod 640 /opt/mattermost/config/config.json
   

3. Regularly Update Packages

   • Keep the OS, Mattermost, and dependencies up to date:

   sudo apt update && sudo apt upgrade -y
   

4. Enable Two-Factor Authentication (2FA)

   • Enforce 2FA for all users via System Console → Authentication → MFA.

⚙️ System & Performance Tuning

1. Enable System Swap

   • Prevent OOM kills:

   sudo fallocate -l 2G /swapfile
     sudo chmod 600 /swapfile
     sudo mkswap /swapfile
     sudo swapon /swapfile
   

2. Optimize PostgreSQL

   • Adjust shared buffers and work memory for your RAM size in /etc/postgresql/XX/main/postgresql.conf.

3. Run Mattermost Behind a Reverse Proxy

   • Let NGINX handle SSL and compression, freeing Mattermost to focus on app logic.

📊 Monitoring & Logging

1. Enable Application Logs

   • Set logging level to INFO or ERROR in config.json.
   • Store logs outside the Mattermost directory (e.g., /var/log/mattermost/).

2. Monitor with Tools

   • Use tools like:
   • Netdata for server metrics
   • Uptime Kuma for endpoint monitoring
   • Fail2Ban to monitor failed logins and ban malicious IPs

3. Systemd Health Checks

   • Ensure mattermost.service restarts on crash with:

   Restart=always
     RestartSec=5
   

Conclusion

You now know how to install and run self-hosted Mattermost instance on Linux VPS. If you followed the guide, you’ve also implemented the hardened server security, performance optimizations, and configured monitoring and logging of the Mattermost service.