Mattermost in Docker. Team chat on your server.

Architecture at a glance

• Mattermost serves plain HTTP on port 8065. TLS is terminated upstream by a reverse proxy (Traefik on the RemarkableCloud App Platform). Set MM_SERVICESETTINGS_SITEURL to the public HTTPS address.
• PostgreSQL is a separate database container and holds all messages, users, and configuration.
• Data volumes hold uploaded files (/mattermost/data), configuration (/mattermost/config), and plugins (/mattermost/plugins, /mattermost/client/plugins).

Docker Compose walkthrough

The standalone stack (Mattermost and PostgreSQL) is defined in the image’s docker-compose.yml:

name: mattermost
services:
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: mattermost
      POSTGRES_PASSWORD: ${DB_PASSWORD:-change-me-db}
      POSTGRES_DB: mattermost
    volumes: [db-data:/var/lib/postgresql/data]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U mattermost"]
      interval: 10s
      timeout: 5s
      retries: 12
  mattermost:
    image: ${MM_IMAGE:-ghcr.io/remarkablecloud/mattermost:11.10.1-r1}
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    ports: ["${HTTP_PORT:-8099}:8065"]
    environment:
      MM_SQLSETTINGS_DATASOURCE: postgres://mattermost:${DB_PASSWORD:-change-me-db}@db:5432/mattermost?sslmode=disable
      MM_SERVICESETTINGS_SITEURL: ${SITE_URL:-http://localhost:8099}
      MM_ADMIN_PASSWORD: ${MM_ADMIN_PASSWORD:-}
    volumes:
      - mm-data:/mattermost/data
      - mm-config:/mattermost/config
      - mm-plugins:/mattermost/plugins
      - mm-client-plugins:/mattermost/client/plugins
volumes:
  db-data:
  mm-data:
  mm-config:
  mm-plugins:
  mm-client-plugins:

Step by step:

1. The app waits for the database. depends_on with condition: service_healthy avoids a first-boot race against PostgreSQL.
2. The admin is created for you. On first boot the image creates a system admin with a generated password (or MM_ADMIN_PASSWORD if set) and logs it once; open sign-up stays disabled.
3. Only the web port is exposed. ${HTTP_PORT:-8099}:8065 is for local use; in production the proxy connects to port 8065 on the internal network.
4. State lives in volumes. The four Mattermost volumes plus db-data persist across restarts and upgrades.

To start it locally:

DB_PASSWORD=$(openssl rand -hex 16) docker compose up -d

Then browse to http://localhost:8099 and read the admin login from docker compose logs mattermost. For production, set MM_SERVICESETTINGS_SITEURL to your HTTPS address and put the container behind a TLS-terminating reverse proxy.

Environment variable reference

These are wired automatically by the App Platform backend from the managed PostgreSQL; they are listed here for standalone and self-hosted runs.

Variable	Required	Value / default	Purpose
MM_SQLSETTINGS_DATASOURCE	yes	postgres://<user>:<pass>@<host>:5432/<db>?sslmode=disable	PostgreSQL connection string.
MM_SERVICESETTINGS_SITEURL	yes	https://<hostname>	Public site URL used for links and CORS.
MM_ADMIN_PASSWORD	no	(generated)	Initial admin password. Leave empty to auto-generate on first run (printed once); set it to pin your own.
MM_ADMIN_USERNAME	no	admin	Initial admin username.
MM_ADMIN_EMAIL	no	admin@example.com	Initial admin email.

The driver (MM_SQLSETTINGS_DRIVERNAME=postgres), local mode, and the closed-signup settings are baked into the image. Only the first boot creates the admin.

Hardening notes

• No public-first-admin. The system admin is created by the image on first boot; open sign-up and email sign-up are disabled by default.
• No baked credentials. The admin password is generated at runtime or supplied by you, never stored in an image layer.
• Digest-pinned base. Each build is auditable and reproducible.
• Healthcheck gates traffic. /api/v4/system/ping must return success before the platform routes requests.
• Keep PostgreSQL private. Do not publish its port to the host or the internet.
• After first login, create your team, invite users (invitations work even with open sign-up off), and keep Mattermost updated.

Backups

Capture the database and the data volume together:

1. The PostgreSQL database:

   docker compose exec db pg_dump -U mattermost mattermost > mattermost-db.sql

2. The data volume (/mattermost/data: uploaded files):

   docker run --rm -v mattermost_mm-data:/data -v "$PWD":/backup alpine \
     tar czf /backup/mattermost-data.tgz -C /data .

On the RemarkableCloud App Platform, database and volume backups follow the platform’s backup schedule.

Upgrades

• New builds ship as new -r tags. Pull the new tag and recreate the container; Mattermost runs its database migrations on start:

  docker compose pull mattermost && docker compose up -d mattermost

• Back up first, and keep the database dump and the /mattermost/data archive from just before the upgrade.
• Read the changelog. Every build is listed in CHANGELOG.md with the base image digest and any behavior changes.