Mattermost 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.

Links:

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: Configure automated backup strategy for Mattermost data 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']

Backup

Back up the following:

  1. Database: Use pg_dump for PostgreSQL backup
  2. Data directory: ${DOCKER_VOLUMES}/mattermost/data
  3. Config directory: ${DOCKER_VOLUMES}/mattermost/config
  4. Plugins: ${DOCKER_VOLUMES}/mattermost/plugins

Example backup script:

# Backup database
docker exec postgresql pg_dump -U mattermost mattermost > mattermost-db-backup.sql

# Backup data directories
tar -czf mattermost-data-backup.tar.gz ${DOCKER_VOLUMES}/mattermost/

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

Resources

name: mattermost
services:
  mattermost:
    image: mattermost/mattermost-team-edition:11.11.1
    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