How to Self-Host Mattermost on a VPS

This guide walks you through installing Mattermost, an open-source Slack alternative, on your own VPS. You’ll get a private, self-managed team chat server with web, desktop, and mobile access. You’ll need a VPS with at least 2 GB of RAM, a domain name pointing to its IP, and basic comfort with the Linux command line.

What You’ll Need

• A VPS running Ubuntu 22.04 or 24.04 (other distros work, but steps differ slightly)
• Root or sudo access to the VPS
• A domain name (e.g., chat.example.com) with an A record pointing to your VPS IP
• Open ports 80 and 443 (HTTP/HTTPS) in your firewall
• SSH client (Terminal on macOS/Linux, PuTTY on Windows)

Step-by-Step

1. Update the system
   SSH into your VPS and run:
   sudo apt update && sudo apt upgrade -y
   This ensures all packages are current.
2. Install MySQL (or MariaDB)
   Mattermost needs a database. Install MySQL with:
   sudo apt install mysql-server -y
   Then secure it:
   sudo mysql_secure_installation
   Follow the prompts to set a root password and remove test databases.
3. Create a database and user
   Log into MySQL:
   sudo mysql -u root -p
   Run these SQL commands (replace mmuser_password with a strong password):
   CREATE DATABASE mattermost CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'mmuser'@'%' IDENTIFIED BY 'mmuser_password';
GRANT ALL PRIVILEGES ON mattermost.* TO 'mmuser'@'%';
FLUSH PRIVILEGES;
EXIT;
4. Download Mattermost
   Get the latest stable version from the official site. As of this writing, the current version is 9.11, but check https://mattermost.com/download/ for the latest. Download and extract:
   wget https://releases.mattermost.com/9.11.0/mattermost-9.11.0-linux-amd64.tar.gz
tar -xvzf mattermost-*.tar.gz
   Move it to /opt:
   sudo mv mattermost /opt
5. Set up directories and permissions
   sudo mkdir -p /opt/mattermost/data
sudo useradd --system --user-group mattermost
sudo chown -R mattermost:mattermost /opt/mattermost
sudo chmod -R g+w /opt/mattermost
6. Configure Mattermost
   Edit the config file:
   sudo nano /opt/mattermost/config/config.json
   Set "SiteURL" to https://chat.example.com (your domain). Under SqlSettings, set "DriverName" to "mysql" and "DataSource" to:
   mmuser:mmuser_password@tcp(localhost:3306)/mattermost?charset=utf8mb4,utf8&readTimeout=10s&writeTimeout=10s
   Save and exit.
7. Set up systemd service
   Create a service file:
   sudo nano /etc/systemd/system/mattermost.service
   Paste:

   [Unit]
   Description=Mattermost
   After=network.target
   
   [Service]
   Type=notify
   User=mattermost
   Group=mattermost
   ExecStart=/opt/mattermost/bin/mattermost
   WorkingDirectory=/opt/mattermost
   Restart=always
   RestartSec=10
   
   [Install]
   WantedBy=multi-user.target

   Enable and start:
   sudo systemctl daemon-reload
sudo systemctl enable mattermost
sudo systemctl start mattermost

8. Install Nginx as reverse proxy
   sudo apt install nginx -y
   Create a site config:
   sudo nano /etc/nginx/sites-available/mattermost
   Paste:

   server {
       listen 80;
       server_name chat.example.com;
   
       location / {
           proxy_pass http://localhost:8065;
           proxy_set_header Host $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;
       }
   }

   Enable it:
   sudo ln -s /etc/nginx/sites-available/mattermost /etc/nginx/sites-enabled/
   Test and reload:
   sudo nginx -t
sudo systemctl reload nginx

9. Enable HTTPS with Certbot
   Install Certbot:
   sudo apt install certbot python3-certbot-nginx -y
   Run:
   sudo certbot --nginx -d chat.example.com
   Follow the prompts; it will automatically configure SSL and renewals.
10. Complete setup in the browser
    Visit https://chat.example.com. Create the first admin account. You’ll be guided to set up a team and invite users.

Common Mistakes

• Wrong database credentials – A typo in the MySQL password or host will cause connection errors. Double-check the DataSource string.
• Firewall blocking ports – If you can’t reach the site, ensure ports 80 and 443 are open in your VPS provider’s firewall and in UFW if enabled (sudo ufw allow 80/tcp and 443/tcp).
• Incorrect SiteURL – If SiteURL is wrong, emails and links will break. Set it exactly to your public URL.
• File permissions – If Mattermost can’t write to /opt/mattermost/data, files and uploads fail. Ensure the mattermost user owns everything.
• Skipping the reverse proxy – Running Mattermost directly on port 8065 without Nginx is fine for testing but not for production; it leaves the server exposed and makes HTTPS harder.

Tips

• Use a dedicated domain – A subdomain like chat.example.com keeps things clean and lets you move servers later.
• Back up regularly – Back up the database and /opt/mattermost/data. Use mysqldump for the DB and rsync for files.
• Set up monitoring – Use UptimeRobot or a similar service to ping your URL and alert you if it’s down.
• Enable email notifications – For production, configure SMTP in System Console > Environment > SMTP to send password resets and notifications.
• Keep Mattermost updated – Check for new releases monthly and follow the upgrade guide; it’s usually just replacing the binary and running migrations.

Troubleshooting

• Site won’t load – Check if Mattermost is running: sudo systemctl status mattermost. Look at logs: sudo journalctl -u mattermost -f. Also test curl http://localhost:8065 from the VPS – if that works, the issue is Nginx or DNS.
• Database connection error – Verify MySQL is running: sudo systemctl status mysql. Test the connection with:
  mysql -u mmuser -p -h localhost mattermost
  If it fails, re-run the GRANT commands.
• HTTPS certificate fails – Ensure your domain resolves to the VPS IP before running Certbot. If it fails, check DNS with dig chat.example.com. Also ensure port 80 is open for the HTTP-01 challenge.
• Uploads fail – Check permissions on /opt/mattermost/data. Run sudo chown -R mattermost:mattermost /opt/mattermost again and restart.
• WebSockets not working (real-time updates) – This is usually a proxy misconfiguration. Ensure you have the Upgrade headers in Nginx. Add these inside the location / block:

  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";

  Then reload Nginx.

Frequently Asked Questions

Can I use SQLite instead of MySQL?

Yes, Mattermost supports SQLite for testing, but it’s not recommended for production. The official docs advise MySQL or PostgreSQL for multi-user setups. If you want to switch later, you’ll need to migrate the database.

How much RAM do I need?

For a small team (up to 25 users), 2 GB is enough. For larger teams or heavy file usage, 4 GB or more is better. The database and app each take about 500 MB.

Can I run Mattermost on a Raspberry Pi?

Technically yes, but it’s not recommended. The ARM build exists, but performance will be poor with more than a few users. A cheap VPS is easier and more reliable.

How do I upgrade Mattermost?

Download the new version, stop the service, replace the binary in /opt/mattermost/bin, and start again. Run sudo systemctl restart mattermost. The database migrations run automatically. Always back up first.

How do I add users?

As an admin, go to System Console > User Management > Users, and click “Create New User.” You can also allow self-registration if you enable it in System Console > Authentication.

Is Mattermost really free?

The Team Edition is free and open-source, but it has some limitations like no LDAP, no guest accounts, and no compliance exports. The Enterprise Edition requires a paid license. For most small teams, Team Edition is sufficient.

Related

• Troubleshoot Workloads Blocked by Cloud Segmentation
• Tripping Circuit Breaker: When to Call an Electrician
• Samsung Notes: Delete a Page Without Deleting the Note