# Mattermost Team Chat

> Enterprise messaging platform with PostgreSQL, Elasticsearch search, and file storage.

- Category: Message Queues & Brokers
- Difficulty: intermediate
- Components: mattermost, postgresql, elasticsearch, minio, nginx
- Tags: mattermost, team-chat, slack-alternative, enterprise, collaboration
- Source: https://docker.recipes/messaging/mattermost-enterprise

## Overview

Mattermost is an open-source, self-hosted team collaboration platform designed as an enterprise alternative to Slack and Microsoft Teams. Originally created by SpinPunch in 2016, Mattermost has evolved into a comprehensive messaging solution that prioritizes data sovereignty, security, and integration capabilities. The platform supports unlimited message history, file sharing, voice calls, and extensive plugin ecosystem while maintaining complete control over your data and infrastructure.

This enterprise-grade deployment combines Mattermost with PostgreSQL for robust message and metadata storage, Elasticsearch for advanced search capabilities across channels and files, MinIO as S3-compatible object storage for file attachments and media, and NGINX as a high-performance reverse proxy. PostgreSQL ensures ACID compliance for critical chat data while supporting Mattermost's complex relational queries. Elasticsearch enables instant search across thousands of messages and channels with relevance scoring. MinIO provides scalable file storage that's compatible with AWS S3 APIs but remains under your control.

This stack is ideal for organizations requiring enterprise-grade team communication with complete data control, compliance teams needing audit trails and data retention policies, development teams wanting extensive integrations and custom bots, and companies migrating from proprietary solutions like Slack while maintaining advanced features. The combination delivers production-ready performance with the flexibility to customize authentication, integrate with existing LDAP/SAML systems, and scale across multiple teams and departments.

## Features

- PostgreSQL backend with ACID compliance for reliable message storage and complex user permission queries
- Elasticsearch integration for full-text search across messages, files, and user profiles with relevance ranking
- MinIO S3-compatible object storage for unlimited file attachments, image previews, and media sharing
- NGINX reverse proxy with SSL termination, request buffering, and WebSocket support for real-time messaging
- Bleve search indexing as fallback when Elasticsearch is unavailable, stored in persistent Docker volumes
- Multi-database support through PostgreSQL's JSON capabilities for plugin data and custom integrations
- High-availability file storage with MinIO's erasure coding and bucket lifecycle management
- Advanced PostgreSQL full-text search capabilities as backup to Elasticsearch cluster

## Use cases

- Enterprise team communication replacing Slack or Microsoft Teams with on-premises data control
- Software development teams needing GitLab, Jira, and CI/CD pipeline integrations with custom webhooks
- Healthcare and financial organizations requiring HIPAA/SOX compliance with audit logging and data retention
- Remote-first companies needing persistent chat history, file sharing, and voice/video calling infrastructure
- Government agencies requiring air-gapped communication systems with classified data handling
- Educational institutions managing student and faculty communication across multiple departments
- Managed service providers offering white-labeled team collaboration platforms to clients

## Prerequisites

- Minimum 6GB RAM (PostgreSQL 1GB + Elasticsearch 2GB + MinIO 1GB + Mattermost 1GB + system overhead)
- Docker Engine 20.10+ and Docker Compose v2 for health check dependencies and network isolation
- Ports 80, 443, 8065, 9000, and 9001 available for NGINX, Mattermost, and MinIO console access
- Valid SSL certificates for production deployment with HTTPS termination at NGINX
- Basic understanding of Mattermost System Console for Elasticsearch configuration and user management
- PostgreSQL administration knowledge for backup strategies and performance tuning

## docker-compose.yml

```yaml
services:
  mattermost:
    image: mattermost/mattermost-team-edition:latest
    ports:
      - "8065:8065"
    environment:
      MM_SQLSETTINGS_DRIVERNAME: postgres
      MM_SQLSETTINGS_DATASOURCE: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?sslmode=disable
      MM_BLEVESETTINGS_INDEXDIR: /mattermost/bleve-indexes
      MM_FILESETTINGS_DRIVERNAME: amazons3
      MM_FILESETTINGS_AMAZONS3ACCESSKEYID: ${MINIO_ACCESS_KEY}
      MM_FILESETTINGS_AMAZONS3SECRETACCESSKEY: ${MINIO_SECRET_KEY}
      MM_FILESETTINGS_AMAZONS3BUCKET: mattermost
      MM_FILESETTINGS_AMAZONS3ENDPOINT: minio:9000
      MM_FILESETTINGS_AMAZONS3SSL: "false"
    volumes:
      - mattermost_data:/mattermost/data
      - mattermost_logs:/mattermost/logs
      - mattermost_config:/mattermost/config
      - mattermost_plugins:/mattermost/plugins
      - mattermost_bleve:/mattermost/bleve-indexes
    depends_on:
      postgres:
        condition: service_healthy
      minio:
        condition: service_started
    networks:
      - mm-net
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - mm-net
    restart: unless-stopped

  elasticsearch:
    image: elasticsearch:8.11.0
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
      - ES_JAVA_OPTS=-Xms512m -Xmx512m
    volumes:
      - es_data:/usr/share/elasticsearch/data
    networks:
      - mm-net
    restart: unless-stopped

  minio:
    image: minio/minio:latest
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      MINIO_ROOT_USER: ${MINIO_ACCESS_KEY}
      MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY}
    volumes:
      - minio_data:/data
    command: server /data --console-address ":9001"
    networks:
      - mm-net
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - mattermost
    networks:
      - mm-net
    restart: unless-stopped

volumes:
  mattermost_data:
  mattermost_logs:
  mattermost_config:
  mattermost_plugins:
  mattermost_bleve:
  postgres_data:
  es_data:
  minio_data:

networks:
  mm-net:
    driver: bridge
```

## .env

```bash
# PostgreSQL
POSTGRES_USER=mattermost
POSTGRES_PASSWORD=secure_postgres_password
POSTGRES_DB=mattermost

# MinIO
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=secure_minio_password
```

## Usage notes

- Mattermost at http://localhost:8065
- Create MinIO bucket 'mattermost' first
- MinIO Console at http://localhost:9001
- Enable Elasticsearch in System Console

## Troubleshooting

- Mattermost shows 'Database connection failed': Check PostgreSQL health check status and verify POSTGRES_USER/POSTGRES_PASSWORD environment variables match between services
- File uploads fail with S3 errors: Manually create 'mattermost' bucket in MinIO console at localhost:9001 before first use, verify MINIO_ACCESS_KEY credentials
- Search returns no results: Enable Elasticsearch in Mattermost System Console > Environment > Elasticsearch, then run bulk indexing job to populate search index
- 502 Bad Gateway from NGINX: Ensure nginx.conf properly proxies to mattermost:8065 internal hostname, check that Mattermost container is running and healthy
- PostgreSQL container exits with permission errors: Fix Docker volume ownership with 'docker-compose down && docker volume rm postgres_data' then restart
- Elasticsearch fails to start with memory errors: Increase Docker Desktop memory allocation above 4GB or reduce ES_JAVA_OPTS heap size for development environments

