Mattermost

Secure collaboration platform for mission-critical work

Mattermost is a collaboration platform for mission-critical work that accelerates workflow by integrating people, processes, tools and AI infrastructure on a resilient and adaptable platform. The official Docker deployment solution provides enterprise-ready team messaging with extensive customization options.

References

• Home: Mattermost | Collaboration Platform for Mission Critical Work
• Source: GitHub - mattermost/docker: Install Mattermost server via Docker
• Docs: Deploy Mattermost using Containers | Mattermost Documentation

Additional resources

• Official Documentation: Mattermost Documentation
• Docker Deployment Guide: Deploy Mattermost using Containers | Mattermost Documentation
• GitHub Repository: GitHub - mattermost/docker: Install Mattermost server via Docker
• Community Forum: Mattermost Discussion Forums - Discussion forums for Mattermost and our open source community

TODO

TODO: Configure S3-compatible storage (MinIO) for file uploads TODO: Set up GitLab SSO integration (requires mounting PKI chain) TODO: Configure SMTP settings for email notifications TODO: Set up Prometheus metrics endpoint for monitoring TODO: Review and configure Mattermost Calls settings for audio/video

Deployment Guide

Mattermost is a secure collaboration platform for mission-critical work that provides enterprise-ready team messaging with extensive customization options.

Prerequisites

Before deploying Mattermost, ensure the following services are running:

1. PostgreSQL - Database backend (deployed via docker/database/postgresql/postgresql.yaml)
2. Traefik - Reverse proxy for HTTPS access

Database Setup

Mattermost requires its own database within the PostgreSQL instance. Create the database and user before starting Mattermost:

Step 1: Access PostgreSQL Container

docker exec -it postgresql psql -U postgres

Step 2: Create Mattermost Database and User

-- Create the Mattermost user
CREATE USER mattermost WITH PASSWORD 'your-secure-password-here';

-- Create the Mattermost database
CREATE DATABASE mattermost WITH OWNER mattermost;

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE mattermost TO mattermost;

-- Exit psql
\q

Environment Configuration

Add the following variables to your config/docker/<hostname>/.env.mattermost file:

### Mattermost configuration
MATTERMOST_POSTGRES_USER="mattermost"
MATTERMOST_POSTGRES_PASSWORD="your-secure-password-here"
MATTERMOST_POSTGRES_DB="mattermost"

Important: Use the same password you set when creating the PostgreSQL user.

Deployment

Deploy Mattermost using the standard workflow:

# Deploy the service
task docker:apply

# Or use labctl.py directly
scripts/labctl.py service up communication/mattermost

Initial Setup

1. Access Mattermost at: https://mattermost.${MYDOMAIN}/
2. Create the first admin account during initial setup
3. Configure team settings and channels as needed

Configuration

File Permissions

Mattermost container runs as UID/GID 2000. If you encounter permission issues:

sudo chown -R 2000:2000 ${DOCKER_VOLUMES}/mattermost

Site URL

The site URL is automatically configured via the MM_SERVICESETTINGS_SITEURL environment variable to match your domain.

SMTP Configuration

To enable email notifications, add the following environment variables to the compose file:

environment:
  MM_EMAILSETTINGS_ENABLESMTPAUTH: true
  MM_EMAILSETTINGS_SMTPUSERNAME: your-smtp-username
  MM_EMAILSETTINGS_SMTPPASSWORD: your-smtp-password
  MM_EMAILSETTINGS_SMTPSERVER: smtp.example.com
  MM_EMAILSETTINGS_SMTPPORT: 587
  MM_EMAILSETTINGS_FEEDBACKEMAIL: noreply@example.com

S3 Storage (MinIO Integration)

To use MinIO for file uploads instead of local storage:

environment:
  MM_FILESETTINGS_DRIVERNAME: amazons3
  MM_FILESETTINGS_AMAZONS3ACCESSKEYID: minio-access-key
  MM_FILESETTINGS_AMAZONS3SECRETACCESSKEY: minio-secret-key
  MM_FILESETTINGS_AMAZONS3BUCKET: mattermost
  MM_FILESETTINGS_AMAZONS3ENDPOINT: minio.${MYDOMAIN}
  MM_FILESETTINGS_AMAZONS3SSL: true

GitLab SSO

To enable GitLab SSO integration, mount the PKI chain and configure OAuth settings:

volumes:
  - /path/to/gitlab-pki-chain.pem:/etc/ssl/certs/pki_chain.pem:ro

Then configure GitLab OAuth in Mattermost System Console.

Monitoring

Health Check

Check if Mattermost is running:

docker ps | grep mattermost

View Logs

scripts/labctl.py service logs communication/mattermost

Prometheus Metrics

Mattermost exposes metrics at /metrics endpoint. Add to your Prometheus configuration:

- job_name: 'mattermost'
  static_configs:
    - targets: ['mattermost:8067']

Troubleshooting

Connection Refused to PostgreSQL

• Ensure PostgreSQL service is running: docker ps | grep postgresql
• Check if database exists: docker exec -it postgresql psql -U postgres -l
• Verify environment variables in .env file

Permission Denied Errors

sudo chown -R 2000:2000 ${DOCKER_VOLUMES}/mattermost

Cannot Access via Browser

• Check Traefik logs: docker logs traefik
• Verify DNS resolution: nslookup mattermost.${MYDOMAIN}
• Check if service is in proxy network: docker network inspect proxy

Upgrading

To upgrade Mattermost:

1. Check release notes: https://docs.mattermost.com/about/mattermost-release-notes.html
2. Update image tag in docker/communication/mattermost/mattermost.yaml
3. Pull new image and recreate container:

scripts/labctl.py service pull communication/mattermost
scripts/labctl.py service recreate communication/mattermost

Backup

Mattermost’s shared PostgreSQL database is covered by the host-side docker/database/postgresql/backup.yaml export. Restore it with this service’s /config, /data, plugins and index data from the paired B2 application-volume snapshot. Preserve original config/secrets and database ownership. See the backup guide for commands, retention and snapshot selection.

Recovery

1. Stop the destination Mattermost. Follow shared PostgreSQL recovery for its database-mattermost.dump, required roles and original DB ownership.
2. Restore ${DOCKER_VOLUMES}/mattermost/{config,data,plugins,client-plugins,bleve-indexes} from the paired application snapshot and recover original config/secrets, database credentials and expected directory ownership.
3. Start PostgreSQL before the matching Mattermost image; check /api/v4/system/ping before switching clients. Keep outbound notifications and production integrations disconnected on an isolated recovery.

DB and uploaded files are not an atomic capture; verify attachment references and plugin state as part of recovery.

Post-restore check

Check the local system ping, sign in, open a known channel/message and download one existing attachment. Restore the original config/secrets and paired uploads with the database before evaluating missing data.

name: mattermost
services:
  mattermost:
    image: mattermost/mattermost-team-edition:11.11.3@sha256:e743b074894133fe131e2274ef8b5295859084641d6657c0e24fb9b0c26c32c0
    container_name: mattermost
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    pids_limit: 200
    tmpfs:
      - /tmp
    environment:
      TZ: ${TIMEZONE}
      # Database configuration - connects to existing PostgreSQL service
      MM_SQLSETTINGS_DRIVERNAME: postgres
      MM_SQLSETTINGS_DATASOURCE: postgres://${MATTERMOST_POSTGRES_USER}:${MATTERMOST_POSTGRES_PASSWORD}@postgresql:5432/${MATTERMOST_POSTGRES_DB}?sslmode=disable&connect_timeout=10
      # Search index configuration
      MM_BLEVESETTINGS_INDEXDIR: /mattermost/bleve-indexes
      # Site URL configuration
      MM_SERVICESETTINGS_SITEURL: https://mattermost.${MYDOMAIN}
    volumes:
      - ${DOCKER_VOLUMES}/mattermost/config:/mattermost/config
      - ${DOCKER_VOLUMES}/mattermost/data:/mattermost/data
      - ${DOCKER_VOLUMES}/mattermost/logs:/mattermost/logs
      - ${DOCKER_VOLUMES}/mattermost/plugins:/mattermost/plugins
      - ${DOCKER_VOLUMES}/mattermost/client-plugins:/mattermost/client/plugins
      - ${DOCKER_VOLUMES}/mattermost/bleve-indexes:/mattermost/bleve-indexes
    networks:
      - proxy
    labels:
      traefik.enable: true
      traefik.http.routers.mattermost.rule: Host(`mattermost.${MYDOMAIN}`)
      traefik.http.routers.mattermost.middlewares: localaccess@file
      traefik.http.services.mattermost.loadbalancer.server.port: 8065
      homepage.group: Connections
      homepage.name: Mattermost
      homepage.icon: mattermost.png
      homepage.href: https://mattermost.${MYDOMAIN}/
      homepage.description: "Secure collaboration platform for mission-critical work"

networks:
  proxy:
    external: true