Mattermost

Last reviewed Aug 26, 2026 · 899 words

Know where the free line sits before you announce Mattermost to your team, because the features people ask for on day two are exactly the ones behind it. The free edition (Team Edition) gives unlimited users, channels, threads, search, file sharing, the mobile and desktop apps, Playbooks, Calls, webhooks and bots, and single sign-on through GitLab. It does not give LDAP or Active Directory sync, SAML or OpenID Connect, guest accounts, compliance export, high availability, or Elasticsearch-backed search; those start at Professional, which was about $10 per user per month at last check, and some are Enterprise-only. For a 12-person engineering team that logs in with passwords, the free edition is complete. For a 200-person company with an identity provider, price it before you commit, because that is the decision the rest of this guide keeps circling back to.

PostgreSQL and SiteURL: the two settings behind most support threads

Mattermost needs a real database; there is no SQLite mode, and PostgreSQL is the one to run (MySQL support has been winding down for years and I would not start a new install on it). The second setting that trips people is SiteURL. Leave it blank or wrong and login works, but email links, OAuth callbacks, permalinks, and the mobile app all point somewhere else. The minimal compose:

services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: mmuser
      POSTGRES_PASSWORD: change-me
      POSTGRES_DB: mattermost
    volumes:
      - ./db:/var/lib/postgresql/data
    restart: unless-stopped
  mattermost:
    image: mattermost/mattermost-team-edition:latest
    depends_on: [db]
    ports:
      - "8065:8065"
    environment:
      MM_SERVICESETTINGS_SITEURL: https://chat.example.com
      MM_SQLSETTINGS_DRIVERNAME: postgres
      MM_SQLSETTINGS_DATASOURCE: postgres://mmuser:change-me@db:5432/mattermost?sslmode=disable
    volumes:
      - ./mm/config:/mattermost/config
      - ./mm/data:/mattermost/data
      - ./mm/logs:/mattermost/logs
      - ./mm/plugins:/mattermost/plugins
    restart: unless-stopped

Any config.json key can be set as an MM_ environment variable and it wins over the file, which is how you keep secrets out of the volume. The official mattermost/docker repository has a longer version with an nginx container; I prefer my own proxy. Budget 2 GB of RAM for the pair; the Mattermost server is a single Go binary and Postgres is the part that grows.

Websockets, or the client looks broken

Behind a reverse proxy, HTTP works and the app loads, then messages stop appearing until refresh and the status dot goes yellow. That is the websocket upgrade being dropped. Caddy passes it through with a plain reverse_proxy mattermost:8065; nginx needs the Upgrade and Connection headers set explicitly on the /api/v4/websocket path. Also raise the proxy's body size limit to match Mattermost's MaxFileSize (default 100 MB) or uploads fail at the proxy with an error Mattermost never sees. File storage is local disk by default and can be pointed at S3-compatible storage under File Settings, worth doing before the data directory reaches a size you would rather not migrate.

Playbooks stayed in; Boards moved out

The catalogue lists "playbooks and boards". Playbooks, the checklist-driven incident and release runbooks, are still bundled and are the feature that separates Mattermost from a generic chat server for DevOps teams: a checklist per incident, timers, retrospectives, and a channel created per run. Boards (the Focalboard kanban) was removed from the core product in 2023 and lives on as a community-maintained plugin. It still installs from the plugin marketplace, but treat it as a bonus, not a roadmap item. Calls, the built-in voice and screen share, works in the free edition for small groups; larger calls need the separate rtcd service, and recordings and transcripts are paid features.

Integrations are where it earns "developer team"

Incoming and outgoing webhooks, slash commands, and a bot account API are all free, and the GitHub, GitLab, Jira, and Jenkins plugins are first-party. A Gitea webhook posting to a channel takes five minutes. What you do not get is federation: there is no bridging to other Mattermost servers or to Matrix without third-party bots, which is a feature for compliance teams and a limitation for communities. If you came from Slack, the shape will feel familiar, including the walls.

Against the two obvious rivals

Rocket.Chat gives you more for free at the identity layer (LDAP and OAuth without a paid tier) but demands MongoDB with a replica set and has been steering hard toward its paid cloud. Zulip is threaded by topic, which some teams love and some never adapt to, and its self-hosted edition includes LDAP and SAML at no cost. Mattermost wins on the Slack-shaped experience, on Playbooks, and on a single-binary server that is easy to upgrade: pull the new image, restart, migrations run themselves. It loses on the paywall for identity, which for many teams is the whole decision.

What I'd do

Postgres 16 and the Team Edition image in the compose above, SiteURL set on day one, behind Caddy with the body limit raised, file storage on S3-compatible storage if you have it. Turn on GitLab or password login, ignore the plugin marketplace for a week, then add Playbooks the first time an on-call incident would have benefited from a checklist. If you need LDAP or SAML and the budget for Professional is not there, that is when I would install Zulip instead rather than fight it.