Migrations Migrating from Heroku, Render, Hatchbox or Cloud 66? We move your production app within 48 hours →
Self-host Mattermost: your own Slack ← Blog vs. competitors • 11 min read

Self-host Mattermost: your own Slack

Almokhtar Bekkour

Almokhtar Bekkour, Founder, Systems Architect

September 29, 2026 · 11 min read

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.1 rather than latest. 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_SITEURL is 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 public https:// 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_DATASOURCE points at the db service over the internal Docker network. sslmode=disable is correct here because that traffic never leaves the Docker network; it is not exposed to the internet. connect_timeout=10 keeps Mattermost from hanging indefinitely if Postgres is slow to come up.
  • Only Caddy publishes ports to the host. Mattermost listens on 8065 and Postgres on 5432, but both are reachable only on the internal mm-net network, never from the internet directly.
  • Each volume maps to a directory Mattermost writes to. config holds the server settings, data holds every uploaded file, image and attachment, logs holds the server logs, and the two plugins directories hold installed plugins and their client-side bundles. The one that holds user content is data; 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.

Skip the server setup

Launch the Mattermost template on Railyard in one click and get your own team chat with HTTPS already wired up.

14-day trial on every plan. One flat price per team, your servers at your provider's price.

Theme
Colors