Mattermost is an open-source team messaging platform, much like Slack: channels, direct messages, threads, file sharing, search, integrations and mobile apps, running on your server. Teams choose it for data control, compliance, and avoiding per-user SaaS pricing. The free Team Edition covers most small and medium teams.

Other options: Rocket.Chat and Matrix Synapse.

Sizing

Users VPS
Up to ~100 2 vCPU, 4 GB RAM
100–1,000 4 vCPU, 8 GB RAM
Larger Separate database server, more nodes (Enterprise for HA)

Plus disk for file uploads (or S3-compatible storage).

Docker Compose

Mattermost provides an official Docker repository with Compose files and an .env template. The essentials:

git clone https://github.com/mattermost/docker /opt/mattermost-docker
cd /opt/mattermost-docker
cp env.example .env

Edit .env:

DOMAIN=chat.example.com
TZ=Etc/UTC
POSTGRES_USER=mmuser
POSTGRES_PASSWORD=change-me-long
POSTGRES_DB=mattermost
MATTERMOST_IMAGE=mattermost-team-edition
MATTERMOST_IMAGE_TAG=10.5                 # pin a version

Create the volume directories with the right ownership (UID 2000 for Mattermost):

mkdir -p ./volumes/app/mattermost/{config,data,logs,plugins,client/plugins,bleve-indexes}
sudo chown -R 2000:2000 ./volumes/app/mattermost

Start without the bundled Nginx (using your own reverse proxy):

docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml up -d

Mattermost listens on port 8065.

Nginx with WebSockets and HTTPS

Mattermost relies heavily on WebSockets:

upstream mattermost { server 127.0.0.1:8065; keepalive 32; }

server {
    server_name chat.example.com;
    client_max_body_size 100M;

    location ~ /api/v[0-9]+/(users/)?websocket$ {
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 600s;
        proxy_pass http://mattermost;
    }

    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_pass http://mattermost;
    }
    # listen 443 ssl http2; certbot --nginx -d chat.example.com
}

See Nginx WebSocket proxy and Let’s Encrypt.

First setup

  1. Open https://chat.example.com, and create the first account. It becomes the System Admin.
  2. In System Console → Environment → Web Server, set the Site URL to https://chat.example.com.
  3. SMTP (System Console → Environment → SMTP) for invitations, notifications and password resets. See transactional email services.
  4. Signup: disable open account creation, and use invite links or restrict signups to your email domain.
  5. Enable MFA (System Console → Authentication).

Integrations

  • Incoming webhooks: post alerts from monitoring, CI or scripts into channels:
curl -i -X POST -H 'Content-Type: application/json' \
  -d '{"text": "Deploy finished on web1 :white_check_mark:"}' \
  https://chat.example.com/hooks/xxx-generated-key-xxx
  • Slash commands, bots and plugins: GitLab, GitHub, Jira, Jenkins, polls and more.
  • Connect monitoring alerts. See uptime monitoring tools.

Mobile and desktop apps

Official apps for iOS, Android, Windows, macOS and Linux. Users enter your server URL. Push notifications go through Mattermost’s push proxy by default (configurable). Check the notification content settings for privacy.

Backups and upgrades

  • Back up the PostgreSQL database and the volumes/app/mattermost directories (config, data, plugins):
docker compose exec -T postgres pg_dump -U mmuser mattermost > /backups/mattermost-$(date +%F).sql
tar -czf /backups/mattermost-files-$(date +%F).tar.gz ./volumes/app/mattermost

Copy them off-server. See backup strategy.

  • Upgrades: follow Mattermost’s upgrade notes (some versions need database migrations), back up first, change MATTERMOST_IMAGE_TAG, and restart. See updating self-hosted apps.

Security

  • HTTPS only. Restrict the System Console to admins with MFA.
  • Keep PostgreSQL on the internal Docker network, not published.
  • Consider SSO (GitLab, OIDC, or SAML in paid editions).
  • Watch the server’s resources and logs. See server security monitoring.

Quick reference

Item Value
App port 8065
Site URL System Console → Web Server
WebSocket path /api/v4/websocket
Data volumes volumes/app/mattermost/*
Webhook post curl -d '{"text":"…"}' https://chat…/hooks/KEY

Related: Docker Compose and pg_dump and pg_restore.

  • Self-Hosting
  • Chat
  • Docker