← Blog vs. competitors • 11 min read Self-host Mattermost: your own Slack
Follow this on your own server. Start your 14-day trial
Slack bills per active user per month and then, on the free plan, hides everything your team said more than 90 days ago behind an upgrade. The two things that make it useful, the people in it and the history of what they decided, are the two things it charges you more for as they grow. Mattermost does the same job, team channels, direct messages, threaded replies, file sharing, search, bots and integrations, as open-source software you run on your own server. By the end of this guide you’ll have Mattermost running on a box you control, reachable over HTTPS at your own domain, backed by Postgres with its uploaded files on a persistent volume, with real-time messaging actually working and a backup that restores to a consistent point.
Mattermost has two things that a naive Docker setup gets wrong. The first is the reverse proxy: real-time messaging rides a websocket, and if the proxy in front of Mattermost doesn’t pass the connection upgrade through, messages silently stop arriving until someone reloads the page. The second is backups: your data lives in two places that have to be captured together, the Postgres database and the directory of uploaded files on disk, and a dump of one without the other restores to a broken instance. This setup handles both from the start.
What you’ll need
- A server. Mattermost itself is light, but it runs alongside Postgres, so give it room. A 1 vCPU / 2 GB VPS is a sensible floor for a small team; 1 GB works for a handful of people but leaves no headroom once Postgres warms up and a few hundred messages a day flow through. Any Ubuntu 24.04 box works.
- A domain name (or a subdomain of one you already own) with access to its DNS.
- Docker and the Docker Compose plugin on the server (Step 2).
- SSH access and a terminal.
Step 1: Create the server and point a domain at it
Create an Ubuntu 24.04 server with at least 2 GB of RAM and note its public IP.
In your DNS, add an A record for a subdomain, for example chat.yourdomain.com, pointing at that IP:
Type: A
Name: chat
Value: <your server's IP>
TTL: 300
Confirm it resolves before continuing, since TLS depends on it:
dig chat.yourdomain.com +short
That should print your server’s IP, not an old one and not nothing.
Step 2: Install Docker
SSH in and install Docker Engine with the Compose plugin:
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
Log out and back in for the group change to take effect, then check both pieces are present:
docker --version
docker compose version
You should see a Docker version and a Compose version printed, with no “command not found” errors.
Step 3: Lay out the project and its secrets
Create a directory for the stack and an .env file to hold everything that shouldn’t live in the compose file itself:
mkdir -p ~/mattermost && cd ~/mattermost
Create .env with your domain and a database password:
# .env
DOMAIN=chat.yourdomain.com
POSTGRES_USER=mmuser
POSTGRES_PASSWORD=<a long random password>
POSTGRES_DB=mattermost
Generate the password with something you won’t be tempted to shorten:
openssl rand -base64 24
Lock the file down so only your user can read it:
chmod 600 .env
Step 4: Write the Docker Compose file
Mattermost ships in two editions from the same image family. Team Edition is the free, open-source build and is what this guide uses; it covers channels, DMs, threads, file sharing, search, slash commands, webhooks and the plugin system, which is everything a team needs for day-to-day chat. Enterprise Edition is the paid build that adds SSO/SAML, LDAP/AD group sync, compliance exports, data retention policies and high-availability clustering. You can start on Team Edition and switch the image later without migrating data, so there’s no reason to pay before you need any of that.
Create docker-compose.yml:
services:
mattermost:
image: mattermost/mattermost-team-edition:10.1
restart: unless-stopped
depends_on:
db:
condition: service_healthy
environment:
- MM_SQLSETTINGS_DRIVERNAME=postgres
- MM_SQLSETTINGS_DATASOURCE=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}?sslmode=disable&connect_timeout=10
- MM_SERVICESETTINGS_SITEURL=https://${DOMAIN}
volumes:
- mm_config:/mattermost/config
- mm_data:/mattermost/data
- mm_logs:/mattermost/logs
- mm_plugins:/mattermost/plugins
- mm_client_plugins:/mattermost/client/plugins
networks:
- mm-net
db:
image: postgres:16-alpine
restart: unless-stopped
environment:
- POSTGRES_USER=${POSTGRES_USER}
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
- POSTGRES_DB=${POSTGRES_DB}
volumes:
- mm_db:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
interval: 5s
timeout: 5s
retries: 10
networks:
- mm-net
caddy:
image: caddy:2
restart: unless-stopped
ports:
- "80:80"
- "443:443"
environment:
- DOMAIN=${DOMAIN}
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile
- caddy_data:/data
- caddy_config:/config
depends_on:
- mattermost
networks:
- mm-net
networks:
mm-net:
volumes:
mm_config:
mm_data:
mm_logs:
mm_plugins:
mm_client_plugins:
mm_db:
caddy_data:
caddy_config:
A few choices worth explaining:
- The image is pinned to
mattermost/mattermost-team-edition:10.1rather thanlatest. A chat server that silently jumps a major version on a restart, running whatever database migrations that version brings, is not something you want to discover after the fact. You upgrade on your own schedule, covered in Step 7. MM_SERVICESETTINGS_SITEURLis not optional. Mattermost uses it to build the links in push notifications and OAuth redirects and to fetch link previews, and it must be the full publichttps://address. Leave it unset and mobile push notifications, any OAuth login and link unfurling all break in ways that look like unrelated bugs. Setting it here, before first boot, is the honest default.MM_SQLSETTINGS_DATASOURCEpoints at thedbservice over the internal Docker network.sslmode=disableis correct here because that traffic never leaves the Docker network; it is not exposed to the internet.connect_timeout=10keeps Mattermost from hanging indefinitely if Postgres is slow to come up.- Only Caddy publishes ports to the host. Mattermost listens on
8065and Postgres on5432, but both are reachable only on the internalmm-netnetwork, never from the internet directly. - Each volume maps to a directory Mattermost writes to.
configholds the server settings,dataholds every uploaded file, image and attachment,logsholds the server logs, and the twopluginsdirectories hold installed plugins and their client-side bundles. The one that holds user content isdata; it and the database are the pair you back up together in Step 6.
Step 5: Write the Caddyfile and start everything
Real-time messaging in Mattermost rides a websocket at /api/v4/websocket. Every message, typing indicator and presence update comes down that single long-lived connection. Any reverse proxy in front of Mattermost has to pass the HTTP connection upgrade through to that path, or the browser falls back to showing you nothing new until you reload. This is the single most common “messages don’t appear until I refresh” cause, and it almost always traces to an nginx config that forwards normal requests fine but was never told to set Upgrade and Connection headers for the websocket.
Caddy handles that upgrade automatically. It detects the websocket handshake and proxies it without any special directive, so a plain reverse_proxy to port 8065 is all you need and the real-time path just works. Create Caddyfile in the same directory:
{$DOMAIN} {
reverse_proxy mattermost:8065
}
Start the stack:
docker compose up -d
Watch it come up and confirm Caddy actually got a certificate:
docker compose logs -f caddy
You should see a line about a certificate obtained for your domain. Then open https://chat.yourdomain.com in a browser; it should load Mattermost’s setup screen with a valid padlock and no certificate warning. Create your system-admin account there, then create your first team. That account is Mattermost’s own first-run setup; this stack doesn’t configure it for you.
To confirm real-time is working end to end, open the instance in two browser windows, post a message in one, and watch it appear in the other without a reload. If it only shows up after a refresh, jump to the websocket entry in Troubleshooting.
Step 6: Back up the database and the files together
This is the step people get wrong, and they find out when a restore comes back with every attachment a broken link. Mattermost keeps structured data, channels, messages, users, memberships, in Postgres, and every uploaded file, image and pasted screenshot in the /mattermost/data directory on disk. A pg_dump alone is not a backup of Mattermost; restore it without the matching data directory and the messages are there but the files they reference are gone.
Back up both, from the same point in time, and keep them off the server:
# database
docker compose exec -T db pg_dump -U mmuser -Fc mattermost > "mm-db-$(date +%F).dump"
# uploaded files
docker run --rm -v mattermost_mm_data:/data -v $(pwd):/backup alpine \
tar czf /backup/mm-data-$(date +%F).tar.gz -C /data .
Put both in a cron job and copy them to object storage or another machine. A backup that lives only on the server it protects doesn’t survive the failure that destroys the server.
To restore onto a fresh box: bring the stack up once so the volumes exist, stop the Mattermost container, pg_restore the dump into the database, extract the files tarball back into the mm_data volume, then start Mattermost again. The database and the files have to come from the same backup run, or the links between messages and their attachments won’t line up.
Step 7: Upgrade Mattermost without surprises
Check the version you’re running now, read Mattermost’s release notes for everything between it and the version you’re moving to, then bump the tag in docker-compose.yml:
image: mattermost/mattermost-team-edition:10.2
Pull and restart just that service:
docker compose pull mattermost
docker compose up -d mattermost
Mattermost runs any needed database migrations automatically on boot. Two rules keep this boring instead of exciting. First, take a Step 6 backup before every upgrade, no exceptions, because a failed migration is far easier to recover from a dump than to unpick in place. Second, don’t skip more than one major version at a time; Team Edition supports stepping across majors in sequence, and the release notes call out any version you can’t jump straight to. Watch the logs on first boot after the bump and confirm a clean startup with no migration error before you tell anyone it’s done.
The shortcut: do it with Railyard
Everything above, a Postgres-backed Mattermost with its uploaded files on a persistent volume, the required site URL set, and HTTPS with working websockets already wired up, is also a one-click template:
https://app.railyard.run/deploy?template=mattermost
That gives you the same architecture this guide builds by hand: the Mattermost Team Edition container and a dedicated Postgres, with the data directory on a persistent volume so uploads survive restarts and redeploys, SiteURL set to your real domain, and TLS terminated at your own domain with the websocket upgrade passed through. So the two things this guide spends the most care on, the real-time path and the database-plus-files backup pair, are already right.
If you want to understand what runs on your server first, what happens on your server when you connect walks through it, and databases and backups explains how scheduled backups work across every template, not just this one. For how the one-click link format itself works, see deploy button.
Troubleshooting
Messages don’t appear until I reload the page. The websocket isn’t getting through the proxy. Caddy handles the upgrade automatically, so if you’re using the Caddyfile above this shouldn’t happen; if you swapped in nginx, you have to add proxy_set_header Upgrade $http_upgrade; and proxy_set_header Connection "upgrade"; on the location that handles /api/v4/websocket, or the connection downgrades to a normal request that never streams anything new. Confirm the browser’s network tab shows a 101 Switching Protocols response for the websocket request, not a 200 or a 400.
Caddy never gets a certificate, or the browser shows a certificate warning. This is almost always DNS, not Caddy. Run dig chat.yourdomain.com +short from your own machine and confirm it returns the server’s current IP. Let’s Encrypt also needs port 80 reachable from the internet for the initial validation, so check your cloud provider’s firewall or security group allows inbound 80 and 443, not just 443.
The Mattermost container starts then exits, or the logs show permission errors writing to /mattermost/data. Mattermost runs as a non-root user with UID 2000, and every mounted directory has to be writable by it. The named volumes in the compose file above handle this because Docker sets their ownership correctly. If you instead bind-mount a host directory, that directory is owned by root and the container can’t write to it; fix it with chown -R 2000:2000 on the host path before starting. This is a real and common first-boot failure.
Push notifications, OAuth login or link previews are broken, but chat otherwise works. MM_SERVICESETTINGS_SITEURL is unset, wrong, or still pointing at http://. All three of those features build URLs from the site URL, so if it doesn’t match the full public https:// address people actually use, they fail while in-app messaging looks fine. Confirm it’s set to https://chat.yourdomain.com and restart Mattermost.
Mattermost can’t connect to the database, or the container keeps restarting on boot. Check docker compose logs db first. The most common cause is a POSTGRES_PASSWORD that was changed in .env after the Postgres volume was first initialized; Postgres only reads those variables on the very first boot with an empty data directory, so the volume still holds the old password while Mattermost connects with the new one. Either set the password back to match, or remove the mm_db volume and let it initialize fresh (which erases the database, so only do this before you have real data).
Restored a backup and messages are there but every attachment is a broken link. The database and the /mattermost/data directory came from different points in time, or the data tarball wasn’t restored at all. Both halves from Step 6 have to be restored together, from the same run.
FAQ
Is Team Edition enough, or do I need Enterprise? Team Edition, the free build this guide uses, covers channels, DMs, threads, file sharing, search, slash commands, incoming and outgoing webhooks and the plugin system, which is the full day-to-day chat experience. Enterprise adds SAML/SSO, LDAP group sync, compliance and data-retention features and HA clustering. Most teams run entirely on Team Edition; you can switch the image later without migrating data if you ever need the rest.
Do I need Postgres, or can Mattermost use something lighter? Postgres is what current Mattermost supports and what this guide uses. Older releases also supported MySQL, but Postgres is the recommended and actively developed path, so there’s no reason to start anywhere else.
How much does this cost to run? The server, roughly $12/month for a 2 GB VPS. Mattermost Team Edition itself is free, with no per-user fee and no cap on message history, which is the whole point against Slack’s per-active-user billing and its 90-day free-plan history limit.
Can my team use the mobile and desktop apps, not just the browser? Yes. The official Mattermost iOS, Android and desktop apps all point at your own server, you enter your https://chat.yourdomain.com address on first launch. Mobile push notifications depend on SiteURL being set correctly, which is one more reason Step 4 sets it from the start.
Do I have to use Caddy? No, nginx or Traefik work the same way. The one thing any reverse proxy in front of Mattermost must get right is passing the websocket upgrade through to /api/v4/websocket. Caddy does it automatically; with nginx you have to set the Upgrade and Connection headers yourself, and forgetting to is the number-one cause of messages not appearing in real time.
Either path gets you the same thing: your own team chat, your own messages and files, full history that doesn’t expire, and a bill that doesn’t move every time someone new joins the team.
Why people pick Railyard for this
- Your own cloud account. Deploy to DigitalOcean, Hetzner, Vultr, AWS, OVHcloud, or any Linux server over SSH, billed directly by your provider with no markup.
- One flat price per team. Launch is $22 a month with 2 servers and 1 seat. Scale is $45 with 5 servers and 5 seats, Team is $79 with 10 servers and 15 seats, and Agency is $149 with 20 servers and unlimited seats. Unlimited apps on every plan, no charge per app, per deploy or per gigabyte, and a 14-day trial to start.
- One-click templates. Deploy open-source apps, like databases, analytics and dev tools, to your own server in one click.
- Managed databases. Postgres, MySQL and Redis with scheduled, restore-verified backups and point-in-time recovery.
- Push-to-deploy. Deploy from GitHub, GitLab or the CLI, with automatic HTTPS and zero-downtime releases.