Install Mattermost on Debian 11 – A No‑Fuss Guide
In this quick walkthrough you’ll get a fully‑functional Mattermost team chat running on a fresh Debian 11 machine, set up as a system service that starts automatically and listens on the usual web port.
1. Prerequisites
Before we dive in, make sure your server is up to date and has the basic stuff Debian ships with:
sudo apt update && sudo apt upgrade -y sudo apt install -y wget git curl gnupg ca-certificates
If you’re on a minimal install (no GUI), that’s all you need.
Debian’s package manager pulls in the right versions of libcurl, libc6 and others that Mattermost depends on.
2. Create a Dedicated Mattermost User
Running chat software as root is a bad habit. Create a lightweight account:
sudo useradd -r -m -d /opt/mattermost -s /bin/false mattermost
Give it a home directory because the app stores its logs there.
This keeps file permissions tidy and protects your system from accidental writes.
3. Install PostgreSQL (or MariaDB)
Mattermost works best with a real database, not SQLite on a production box. I’ve seen people ship a server that crashes when the chat load spikes because they stuck with SQLite. Skip that.
sudo apt install -y postgresql postgresql-contrib
Create a role and database for Mattermost:
sudo -u postgres psql <<EOF CREATE ROLE mattermost WITH LOGIN PASSWORD 'changeMe!'; ALTER USER mattermost CREATEDB; CREATE DATABASE mattermost OWNER mattermost; \q EOF
A dedicated PostgreSQL user isolates data and avoids permission errors when Mattermost writes to the DB.
4. Download and Extract Mattermost
Grab the latest stable release from the official site:
cd /opt/mattermost sudo wget https://releases.mattermost.com/6.9.0/mattermost-6.9.0-linux-amd64.tar.gz sudo tar -xzf mattermost-6.9.0-linux-amd64.tar.gz --strip-components=1
Change ownership so the Mattermost user owns everything:
sudo chown -R mattermost:mattermost /opt/mattermost
If files are owned by root, the service won’t be able to write logs or temp files.
5. Configure Mattermost
Edit the config.json file to point at PostgreSQL:
sudo nano /opt/mattermost/config/config.json
Find "DriverName": "postgres" and set these values:
"DataSource": "postgres://mattermost:changeMe!@localhost:5432/mattermost?sslmode=disable&connect_timeout=10",
Also, change the SiteURL to match your domain or IP.
A mis‑typed DSN is a common rookie mistake that results in “database unreachable” errors.
6. Create a Systemd Service File
Create /etc/systemd/system/mattermost.service:
sudo nano /etc/systemd/system/mattermost.service
Paste:
[Unit] Description=Mattermost Server After=network.target [Service] User=mattermost Group=mattermost WorkingDirectory=/opt/mattermost ExecStart=/opt/mattermost/bin/mattermost server Restart=always LimitNOFILE=49152 [Install] WantedBy=multi-user.target
Reload systemd and enable the service:
sudo systemctl daemon-reload sudo systemctl enable mattermost --now
The LimitNOFILE setting prevents “too many open files” errors under load.
If you forget to set User= correctly, the service will start as root and then immediately die with a “permission denied” message—an annoyance I’ve seen on dozens of fresh installs.
7. Open the Firewall (Optional but Recommended)
sudo ufw allow 8065/tcp
Mattermost listens on port 8065 by default.
Without this rule, you’ll get “connection refused” even though the server is running.
8. Verify Everything Works
Open a browser to http://your‑server-ip:8065. You should see the Mattermost welcome screen. Log in with the default admin credentials:
Username: sysadmin Password: sysadmin
Change the password immediately and create your first team.
A quick sanity check confirms that PostgreSQL, file permissions, and systemd are all cooperating.
If you hit a snag where logs say “Failed to bind port 8065,” double‑check that no other process is using it:
sudo ss -tuln | grep :8065
That usually points to an old instance still running or a mis‑configured firewall rule.
Enjoy your new chat platform—no more shouting into the void, just clean, self‑hosted messaging.
