Mattermost Production Guide

Mattermost is an open-source, self-hosted messaging platform designed as a Slack alternative for organizations that need to keep their communications data on-premises or within their own cloud accounts. Built by Mattermost, Inc. (founded 2016, originating from SpinPunch Inc.'s internal chat tool open-sourced in 2015), it provides channels, direct messages, threaded conversations, file sharing, and search — all under your control.

The platform is written in Go on the backend and React on the frontend, delivering a modern chat experience that teams can deploy behind their firewall. Mattermost positions itself specifically for security-conscious organizations in government, defense, financial services, and healthcare where data sovereignty is non-negotiable.

Core messaging concepts

• Channels — Public and private channels organize conversations by topic, project, or team. Similar to Slack channels
• Direct messages — One-on-one and group DMs for private conversations outside of channels
• Threads — Threaded replies keep discussions organized within channels, preventing important context from being lost in scroll
• File sharing — Drag-and-drop file uploads with preview support for images, PDFs, and code files
• Search — Full-text search across all messages, with filters by channel, user, and date range

Positioning vs. Slack and Microsoft Teams

Mattermost follows a straightforward three-tier architecture: a stateless application server, a relational database, and a file storage backend. Real-time message delivery is handled via WebSocket connections.

Backend — Go application server

The Mattermost server is a single Go binary that handles HTTP REST API requests, WebSocket connections for real-time messaging, plugin execution, and scheduled jobs (e.g., data retention, LDAP sync). It is stateless by design, which means you can run multiple instances behind a load balancer for horizontal scaling.

Frontend — React web application

The web client is a React single-page application served by the Go server. Desktop clients (Windows, macOS, Linux) are Electron wrappers around the same React app. Mobile clients (iOS, Android) use React Native. All clients communicate with the server via the REST API and WebSocket.

Database

PostgreSQL is the recommended database. MySQL is also supported but PostgreSQL receives more testing and better optimization from the Mattermost team. The database stores users, channels, messages, reactions, file metadata, configuration, and all application state.

File storage

Uploaded files (images, documents, attachments) are stored separately from the database. Supported backends include:

• Local filesystem — Simple, but not suitable for HA (unless on shared storage like NFS)
• Amazon S3 — Recommended for production. Supports any S3-compatible API
• MinIO — Self-hosted S3-compatible storage. Good for on-prem deployments

Reverse proxy

Nginx or HAProxy sits in front of Mattermost to handle TLS termination, static file serving, and WebSocket upgrade. The reverse proxy is critical for production — never expose the Mattermost port directly to the internet.

Mattermost can be deployed in several ways depending on scale, infrastructure, and operational maturity. Each method trades simplicity for flexibility.

Recommended production setup

For a production deployment serving 500+ users, the recommended architecture is:

• 2+ Mattermost app nodes behind a load balancer
• PostgreSQL with streaming replication (primary + replica)
• S3 or MinIO for file storage (shared across nodes)
• Nginx or HAProxy as reverse proxy with TLS termination
• Elasticsearch or OpenSearch (optional, Enterprise) for improved search performance at scale. The experimental Bleve search engine was retired in v11

# Example: Docker Compose quickstart
git clone https://github.com/mattermost/docker
cd docker
cp env.example .env
# Edit .env to set domain, database credentials, etc.
docker compose -f docker-compose.yml -f docker-compose.nginx.yml up -d

Mattermost supports high availability through a multi-node cluster architecture. Multiple Mattermost application servers run behind a load balancer, sharing the same database and file storage backend. This provides both redundancy and horizontal scaling.

Cluster mode

Mattermost cluster mode uses a gossip protocol for inter-node communication. When a message is posted on one node, it is broadcast to all other nodes via the cluster, which then push the message to their connected WebSocket clients. This ensures all users see messages in real-time regardless of which node they are connected to.

• Enable clustering in config.json under ClusterSettings
• All nodes must share the same ClusterName and the same database
• Nodes discover each other via gossip (Hashicorp Memberlist) on a configurable port, with AES-256 encryption by default

Database HA

The database is typically the single point of failure. Options for database high availability include:

Shared file storage

In a multi-node cluster, file storage must be shared. Local filesystem storage will not work because a file uploaded to node A will not be accessible from node B. Use S3 or MinIO as the file backend for any HA deployment.

Load balancing

The load balancer must support WebSocket connections. Configure:

• WebSocket sticky sessions — Use IP hash or cookie-based session affinity so that a user's WebSocket connection stays on the same backend node. This prevents reconnection storms.
• Health checks — Use the /api/v4/system/ping endpoint to determine node health
• TLS termination — Terminate TLS at the load balancer and use plain HTTP to backends (or re-encrypt if required)

Mattermost provides a rich integration ecosystem that lets teams connect their messaging platform with the tools they already use. Integrations range from simple webhooks to full server-side plugins.

Webhooks

• Incoming webhooks — Accept HTTP POST requests from external services and post messages to a channel. Great for CI/CD notifications, monitoring alerts, and custom integrations
• Outgoing webhooks — Trigger an HTTP POST to an external URL when a message matches a pattern or is posted to a specific channel. Useful for building custom bot responses

Slash commands

Custom slash commands let users trigger external actions from the message input. When a user types /deploy production, Mattermost sends a POST request to your configured endpoint, which can execute the deployment and return a response message.

Bots

Bot accounts are special accounts that can post messages, respond to events, and interact with channels via the REST API. Unlike webhooks, bots can listen to events across multiple channels and maintain state. Bots authenticate via personal access tokens.

Plugin ecosystem

The plugin system is Mattermost's most powerful integration mechanism. Plugins run inside the server process and can extend both the backend (Go) and the frontend (React).

Plugin marketplace

The Mattermost Plugin Marketplace is accessible from the System Console. It provides one-click install for community and Mattermost-maintained plugins. In air-gapped environments, plugins can be uploaded manually as .tar.gz bundles.

REST API

The Mattermost REST API (v4) provides full programmatic access to every feature: users, channels, posts, files, teams, roles, and system configuration. All integrations ultimately use this API. Authentication is via bearer tokens (personal access tokens or OAuth 2.0).

# Example: Post a message via the REST API
curl -X POST https://mattermost.example.com/api/v4/posts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "channel_id_here",
    "message": "Deployment to production completed successfully."
  }'

Mattermost supports multiple authentication backends that can be configured to match enterprise identity infrastructure. Multiple authentication methods (email, LDAP, SAML, OIDC) can be enabled system-wide simultaneously, but each user account is assigned to a single authentication method. Switching a user between methods requires first switching to email, then to the target method.

LDAP / Active Directory

• Connect to LDAP/AD for user authentication and profile sync
• Configurable attribute mapping (username, email, first/last name, nickname)
• LDAP group sync maps AD groups to Mattermost teams and channels (Enterprise)
• Scheduled sync interval pulls user changes from the directory
• Supports LDAP over TLS (LDAPS) and STARTTLS

SAML 2.0

SAML single sign-on integrates with identity providers like Okta, Azure AD, ADFS, OneLogin, and Keycloak. Mattermost acts as the Service Provider (SP). SAML provides:

• Single sign-on and single sign-out
• Attribute mapping from SAML assertions to user fields
• Group sync via SAML group assertions (Enterprise)
• Certificate-based trust between IdP and SP

OpenID Connect (OIDC)

OIDC is the recommended approach for modern identity setups. Supported providers include:

Multi-factor authentication (MFA)

Mattermost supports TOTP-based MFA (Google Authenticator, Authy, etc.). MFA can be enforced system-wide so that all users must configure a second factor. When using SAML or OIDC, MFA should be handled at the identity provider level rather than in Mattermost.

Guest accounts

Guest accounts allow external collaborators (vendors, contractors, partners) to participate in specific channels without having full team membership. Guests can only see channels they are explicitly invited to, and their permissions are restricted by default.

Mattermost uses a hierarchical permission model based on system roles, team roles, and channel roles. Understanding this model is critical for properly securing a deployment.

Channel types

• Public channels — Visible to all team members. Anyone can join. Good for broad topics like #general, #engineering, #announcements
• Private channels — Invite-only. Not visible in channel listings to non-members. Used for sensitive discussions, HR, security teams
• Direct messages — One-on-one conversations between two users
• Group messages — Ad-hoc conversations between 3-7 users (default limit, configurable) without creating a formal channel

Team management

Mattermost organizes users into teams. Each team has its own set of channels, and users can belong to multiple teams. Teams can be open (anyone can join) or invite-only. In large organizations, teams typically map to departments or business units.

Permission schemes

Permission schemes allow administrators to customize what each role can do at the system, team, and channel level. This is an Enterprise feature that provides fine-grained control over:

• Who can create public/private channels
• Who can delete or archive channels
• Who can manage channel members
• Who can post in read-only announcement channels
• Who can use slash commands or integrations

Channel moderation

Channel moderation (Enterprise) allows overriding permissions on a per-channel basis. For example, you can create an #announcements channel where only admins can post but everyone can read and react. This is configured per-channel in the channel settings.

Compliance exports

For regulated industries, Mattermost Enterprise supports compliance exports in Actiance XML, Global Relay EML, and CSV formats. Exports can be scheduled to run daily and include all messages, file metadata, edits, and deletions. This is required for financial services (FINRA, SEC), healthcare (HIPAA), and government (FedRAMP) compliance.

Mattermost provides multiple interfaces for system administration, from a web-based System Console to the mmctl command-line tool.

System Console

The System Console is a web UI accessible to system administrators at /admin_console. It provides configuration for every aspect of the server: authentication, notifications, file storage, plugins, compliance, reporting, and more. Changes made in the System Console are written to config.json (or the database if using database config).

mmctl — command-line administration

The mmctl tool is a remote CLI that communicates with Mattermost via the REST API. It replaces the older mattermost CLI and can be run from any machine, not just the server host.

# Common mmctl commands
mmctl auth login https://mattermost.example.com
mmctl user list
mmctl channel create --team myteam --name new-channel --display-name "New Channel"
mmctl post create myteam:town-square --message "Server maintenance at 2am"
mmctl plugin install plugin-id
mmctl config set ServiceSettings.EnableDeveloper true

Bulk import/export

Mattermost supports bulk import/export in JSONL format for migrating data between instances or from other platforms (Slack, HipChat, MS Teams). The bulk import handles users, teams, channels, posts, reactions, and file attachments.

# Export data
mmctl export create
mmctl export download export-file.zip

# Import from Slack
mmctl import process slack-export.zip

Data retention policies

Enterprise deployments can configure automatic data retention policies that delete messages and files older than a specified number of days. Policies can be applied globally or per-channel. This is essential for compliance (some regulations require deletion after a period) and for managing storage growth.

Custom branding

Mattermost supports custom branding including: custom site name, custom login page text, custom brand image on the login screen, and custom link in the help menu. Enterprise adds the ability to customize announcement banners and the about page.

Custom emoji

Users can upload custom emoji (if permitted by the system admin). Custom emoji are stored in the file backend and available to all users on the server. This is a small but important feature for team culture and engagement.

Mattermost uses an open-core licensing model. The free edition provides a fully functional messaging platform, while paid editions add enterprise features for compliance, scale, and administration.

Licenses are applied in the System Console under Edition and License. The license is a JSON file tied to the organization name, user count, and expiration date. When a license expires, Enterprise features are disabled but the server continues to function on Free edition capabilities.

Use this checklist when evaluating or deploying Mattermost for a client.