Deploying Mattermost HA with Docker Swarm: A Practical Guide

Problem: a single Mattermost instance creates a single point of failure

When your team relies on Mattermost for daily communication, a crashed container or a failed host can halt conversations, delay incident response, and erode trust. Adding redundancy manually with separate load balancers, database replicas, and custom scripts quickly becomes error‑prone.

Thesis: Docker Swarm gives you a built‑in, self‑healing HA stack for Mattermost

By running the Mattermost app, a shared PostgreSQL database, and a shared object store (MinIO or S3) as replicated services in a Swarm cluster, you get automatic task rescheduling, traffic distribution via the routing mesh, and consistent data across replicas—all without an external load balancer.

Architecture overview

The HA design consists of three logical layers:

• App replicas – the Mattermost web/API containers, scaled to the desired replica count.
• Data layer – a single PostgreSQL service (replicated via Swarm but backed by a persistent volume or external DB) and an object‑store service (MinIO) that holds file uploads, avatars, and plugins.
• Routing mesh – Swarm’s built‑in load balancer that forwards incoming HTTP/HTTPS to any healthy app task on any node.

All app tasks read/write to the same PostgreSQL instance and the same MinIO bucket, guaranteeing that chat history and files stay consistent regardless of which node serves a request.

Preparing the Swarm

1. Initialize Swarm on a manager node (run as a user in the docker group or with sudo):

   docker swarm init --advertise-addr <MANAGER_IP>

2. Join worker nodes:

   docker swarm join --token <WORKER_TOKEN> <MANAGER_IP>:2377

3. Create an overlay network for the stack (optional but recommended):

   docker network create --driver overlay mattermost_net

Worked example: deploy the stack and verify failover

Use the official docker-swarm directory from the Mattermost Docker repository. The provided docker-stack.yml defines three services: mattermost-app, mattermost-db, and mattermost-minio.

1. Deploy the stack (replace <STACK_NAME> with a name of your choice, e.g., mmprod):

   docker stack deploy -c docker-stack.yml <STACK_NAME>

2. Check that services are running with the expected replica count (default is 2 app replicas):

   docker service ls

   You should see something like:

   ID                  NAME                MODE                REPLICAS            IMAGE
   abc123              mmprod_mattermost-app   replicated          2/2                 mattermost/mattermost-team-edition:latest
   ...

3. Verify health (Swarm will mark a task as RUNNING only after the container’s healthcheck passes):

   docker service ps <STACK_NAME>_mattermost-app

4. Test automatic failover by draining a node:

   # Identify a node ID
   docker node ls
   # Drain the node (replace <NODE_ID>)
   docker node update --availability drain <NODE_ID>
   

   After the drain, watch the app tasks:

   docker service ps <STACK_NAME>_mattermost-app

   You should see the tasks that were on the drained node shift to SHUTDOWN and new tasks appear on other nodes with a RUNNING state. The routing mesh continues to direct traffic to the healthy tasks, so users experience no downtime as long as at least one replica remains active.

Trade‑offs and limitations

• Resource sizing – Too many app replicas can overwhelm the shared PostgreSQL or MinIO backend, causing connection errors or slowdowns. Monitor pg_stat_activity and MinIO request logs, and adjust the replica count based on observed load.
• No automated backups – Swarm keeps services running but does not snapshot the PostgreSQL database or the object store. You must implement a separate backup strategy (e.g., pg_dump cron jobs, MinIO versioning, or snapshots of the underlying volumes).
• Single point of failure for the data layer – The HA design assumes a resilient PostgreSQL deployment (e.g., managed service, Patroni cluster, or external replicated DB) and a durable object store. If those layers fail, the app replicas cannot serve correct data.

Actionable closing

To keep your Mattermost HA deployment healthy:

1. Set monitoring alerts on service replica counts (docker service ls) and on task health (docker service ps).

2. Schedule regular backups of PostgreSQL and MinIO, and test restore procedures quarterly.

3. When traffic grows, increase mattermost-app replicas incrementally, checking database connection usage after each step.

4. If you need to update the Mattermost version, edit the image tag in docker-stack.yml and run docker stack deploy -c docker-stack.yml <STACK_NAME> again; Swarm will perform a rolling update.

By treating the Swarm stack as the source of truth for your chat platform, you gain automated failover and scaling while retaining full control over data protection and capacity planning.