# Mattermost + PostgreSQL + Elasticsearch

> Self-hosted Slack alternative with enterprise features.

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

## Overview

Mattermost is an open-source team collaboration platform that provides Slack-like messaging, file sharing, and communication features while maintaining full control over your data. Originally developed by SpinPunch in 2015, Mattermost has evolved into a comprehensive team communication solution that prioritizes security, compliance, and self-hosting capabilities. Unlike cloud-based alternatives, Mattermost allows organizations to deploy messaging infrastructure on their own servers, making it ideal for companies with strict data governance requirements or those operating in regulated industries. This stack combines Mattermost with PostgreSQL for robust data storage, Elasticsearch for advanced search capabilities, and NGINX for reverse proxy functionality. PostgreSQL provides ACID-compliant transaction support and handles Mattermost's complex relational data requirements including user management, channel permissions, and message threading. Elasticsearch enables enterprise-grade search features across messages, files, and user content with real-time indexing and relevance scoring. NGINX acts as the web server and reverse proxy, handling SSL termination, load balancing, and serving static assets efficiently. This combination is particularly valuable for organizations needing enterprise-grade team communication with advanced search, audit trails, and compliance features. The stack supports everything from small development teams to large enterprises with thousands of users, while maintaining the flexibility to integrate with existing authentication systems, custom plugins, and third-party tools through Mattermost's extensive API ecosystem.

## Features

- Advanced message search with Elasticsearch full-text indexing and relevance scoring
- PostgreSQL-backed user authentication with support for LDAP, SAML, and OAuth integration
- Real-time messaging with WebSocket connections proxied through NGINX
- File sharing and preview capabilities with metadata stored in PostgreSQL
- Thread-based conversations with PostgreSQL ensuring message relationship integrity
- Elasticsearch-powered channel and user discovery across large deployments
- NGINX SSL termination with HTTP/2 support for improved mobile app performance
- Plugin marketplace with custom integrations stored and managed via PostgreSQL

## Use cases

- Enterprise teams requiring on-premises chat with compliance and audit logging
- Development teams needing GitHub, GitLab, and Jenkins integrations with searchable history
- Remote organizations wanting Slack-like features without vendor lock-in
- Healthcare or financial institutions requiring HIPAA or SOX compliant messaging
- Open-source projects needing community communication with extensive search capabilities
- Companies migrating from Slack who want to maintain chat history and integrations
- Educational institutions providing secure student and faculty communication platforms

## Prerequisites

- Minimum 4GB RAM (2GB for Elasticsearch, 1GB for PostgreSQL, 1GB for Mattermost)
- Docker Engine 20.10+ and Docker Compose 2.0+ installed
- Ports 80, 443, and 8065 available on the host system
- Basic understanding of NGINX configuration for SSL certificate setup
- At least 20GB available disk space for PostgreSQL and Elasticsearch data
- Knowledge of Mattermost System Console for initial team and user configuration

## docker-compose.yml

```yaml
services:
  mattermost:
    image: mattermost/mattermost-enterprise-edition:latest
    environment:
      - TZ=UTC
      - MM_SQLSETTINGS_DRIVERNAME=postgres
      - MM_SQLSETTINGS_DATASOURCE=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/mattermost?sslmode=disable
      - MM_ELASTICSEARCHSETTINGS_ENABLEINDEXING=true
      - MM_ELASTICSEARCHSETTINGS_ENABLESEARCHING=true
      - MM_ELASTICSEARCHSETTINGS_CONNECTIONURL=http://elasticsearch:9200
      - MM_SERVICESETTINGS_SITEURL=http://localhost
      - MM_FILESETTINGS_DIRECTORY=/mattermost/data
    volumes:
      - mattermost-data:/mattermost/data
      - mattermost-logs:/mattermost/logs
      - mattermost-config:/mattermost/config
      - mattermost-plugins:/mattermost/plugins
    ports:
      - "8065:8065"
    depends_on:
      - postgres
      - elasticsearch
    networks:
      - mattermost-network
    restart: unless-stopped

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=mattermost
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - mattermost-network
    restart: unless-stopped

  elasticsearch:
    image: elasticsearch:7.17.10
    environment:
      - discovery.type=single-node
      - ES_JAVA_OPTS=-Xms512m -Xmx512m
    volumes:
      - es-data:/usr/share/elasticsearch/data
    networks:
      - mattermost-network
    restart: unless-stopped

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

volumes:
  mattermost-data:
  mattermost-logs:
  mattermost-config:
  mattermost-plugins:
  postgres-data:
  es-data:

networks:
  mattermost-network:
    driver: bridge
```

## .env

```bash
# Mattermost
POSTGRES_USER=mattermost
POSTGRES_PASSWORD=secure_postgres_password

# Site URL for proper linking
MM_SERVICESETTINGS_SITEURL=http://localhost
```

## Usage notes

- Mattermost at http://localhost:8065
- Create first admin on signup
- Elasticsearch for advanced search
- Enable plugins in System Console
- Mobile apps available

## Troubleshooting

- Elasticsearch fails to start with 'max virtual memory areas vm.max_map_count too low': Run 'sudo sysctl -w vm.max_map_count=262144' on the host
- Mattermost shows database connection errors: Verify POSTGRES_USER and POSTGRES_PASSWORD environment variables match between services
- Search functionality not working in Mattermost: Check Elasticsearch container logs and ensure MM_ELASTICSEARCHSETTINGS_* variables are properly configured
- NGINX returns 502 Bad Gateway errors: Confirm Mattermost container is running and accessible on port 8065 within the Docker network
- PostgreSQL container exits with 'database system was shut down': Check available disk space and ensure postgres-data volume has proper permissions
- Mattermost plugins fail to install: Verify mattermost-plugins volume is mounted and container has write permissions to /mattermost/plugins

