Architecture overview

Available on all plans

self-hosted deployments

This page provides an overview of the Mattermost architecture with reference architecture. For a more detailed deployment overview, check out our deployment wiki.

Basics

At its core, Mattermost is a single-compiled Go binary that is exposed as a Restful JSON web server with Javascript and Go clients. See the Restful API docs here.

It is configured using config/config.json and provides the following:

• Authentication client: The functionality for users to log into Mattermost via email address and password in Team Edition. Mattermost Professional adds the ability for users to authenticate using Active Directory or LDAP, and Mattermost Enterprise adds the ability to authenticate using SAML SSO providers like ADFS, OneLogin, and Okta.

• Authentication provider: Enables the Mattermost server to authenticate to other services like GitLab and Zapier using OAuth 2.0.

• Notification service: Sends notifications via SMTP or a Push Notification Service for mobile applications.

• Data management service: Connects to supported databases and file storage solutions (local, network-attached storage, Amazon S3, etc), and manages the reading and writing of data between them.

The binary talks to a database, typically PostgreSQL, and a filestore. See the Migrate from MySQL to PostgreSQL product documentation for details on migrating from MySQL to PostgreSQL.

Push notification service

The Mattermost hosted push notification service can be used to send push notifications to mobile clients. Team Edition users can deploy the service using the Mattermost test push notification service or host their own push notification service and compile their mobile applications to use that service.

Proxy

A proxy server is a server (a computer system or an application) that acts as an intermediary for requests from clients seeking resources from other servers. Mattermost recommends using a proxy in front of Mattermost to increase security, performance and the ability to monitor and shape traffic connecting to Mattermost:

• Security: A proxy server can manage Secure Socket Layer (TLS/SSL) encryption and set policy on how network traffic will be routed to the Mattermost server.

• Performance: In a High Availability configuration, the proxy server balances the network load across multiple Mattermost servers for optimized performance. A hardware proxy with dedicated devices for processing SSL encryption and decryption can also be used to increase performance.

• Monitoring: A proxy server can monitor connection traffic and record traffic in standard audit logs that common monitoring tools like Kibana and Splunk can consume and report on. Some of the events that can be captured include file uploads and downloads, which are not tracked by the Mattermost server logging process.

Mattermost provides documentation and support for the NGINX proxy. For information on how to install and configure NGINX for your environment, see our deployment guides. Mattermost also unofficially supports other proxies including Apache 2.

Communication protocols

There are also communication protocols (HTTPS and WS) that define the type of connection the user makes with the Mattermost server.

HTTPS Connection (Secure Hypertext Transfer Protocol)

• HTTPS connections to the Mattermost server render pages and provide access to core platform functionality, but do not include real-time interactivity (which is enabled by WSS connections).

• HTTPS is a secure, encrypted protocol and is highly recommended for production. Unencrypted HTTP connections may be used in initial testing and configuration, but should never be used in a production environment.

WSS Connection (Secure WebSocket Protocol)

Secure WebSocket (WSS) connections to the Mattermost Server enable real-time updates and notifications between clients and the server.

If a WSS connection is not available and HTTPS is substituted, the system will appear to work but real-time updates and notifications will not. In this mode of operation, updates will only appear on a page refresh. WSS has a persistent connection to the Mattermost server when a client is connected, while HTTPS has an intermittent connection and only connects to the server when a page or file is requested.

Mattermost services ports

The following table lists the Mattermost services ports for Mattermost Server, push proxy, and mobile app clients. System admins with clients that need to speak to the Mattermost server without a proxy can open specific firewall ports as needed.

Mattermost Server

Service Name	Config Setting	Port (default)	Protocol	Direction	Info
HTTP/Websocket	ServiceSettings.ListenAddress	8065/80/443 (TLS)	TCP	Inbound	External (no proxy) / Internal (with proxy) Usually this requires port 80 and 443 when running HTTPS.
Cluster	ClusterSettings.GossipPort	8074	TCP/UDP	Inbound	Internal
Metrics	MetricsSettings.ListenAddress	8067	TCP	Inbound	External (no proxy) / Internal (with proxy)
Database	SqlSettings.DataSource	5432 (PostgreSQL) / 3306 (MySQL)	TCP	Outbound	Usually internal (recommended)
LDAP	LdapSettings.LdapPort	389	TCP/UDP	Outbound
S3 Storage	FileSettings.AmazonS3Endpoint	443 (TLS)	TCP	Outbound
SMTP	EmailSettings.SMTPPort	10025	TCP/UDP	Outbound
Push Notifications	EmailSettings.PushNotificationServer	443 (TLS)	TCP	Outbound

Push Proxy

Service Name	Config Setting	Port (default)	Protocol	Direction	Info
Push Proxy	ListenAddress	8066	TCP	Inbound	External (no proxy) / Internal (with proxy)

Mobile Clients

In order to receive push notifications, your network must allow traffic on port 5223 for iOS devices and ports 5228-5230 for Android.

High Availability and scalability

Mattermost Enterprise supports:

1. Clustered Mattermost servers, which minimize latency by:

• Storing static assets over a global CDN.

• Deploying multiple Mattermost servers to host API communication closer to the location of end users.

They can also be used to handle scale and failure handoffs in disaster recovery scenarios.

2. Database read replicas, where replicas can be:

• Configured as a redundant backup to the active database server.

• Used to scale up the number of concurrent users.

• Deployed closer to the location of end users, reducing latency.

Moreover, search replicas are also supported to handle search queries.

Reference architectures

The following diagrams show the suggested architecture configurations enterprise deployments of Mattermost at different scales. These diagrams are meant as guidelines for typical Mattermost deployments. Hardware and infrastructure requirements can vary significantly based on usage and policies.

There are two versions of each diagram. One is generalized while the other focuses on AWS.

Each generalized diagram represents a full High Availability deployment across all critical components. The proxy, database, file storage, and Elasticsearch layers can be replaced by cloud services. Push proxy can be replaced by the Mattermost HPNS.

Each AWS diagram represents a full High Availability deployment on Amazon Web Services making full use of the available services. Push proxy can optionally be deployed manually in place of HPNS.

5,000 users on Enterprise - General

5,000 users on Enterprise - AWS

10,000 users on Enterprise - General

10,000 users on Enterprise - AWS

25,000 users on Enterprise - General

25,000 users on Enterprise - AWS

50,000 users on Enterprise - AWS

Database with VIPs

The following diagram is a suggested configuration for Highly-Available databases through virtual IPs.

Load testing

Mattermost Enterprise Edition was load tested with 60,000 concurrent active users with:

• Six Mattermost servers: m4.2xlarge (8 vCPU, 32 GB RAM)

• One MySQL database server with five read replicas: db.r4.2xlarge (8 vCPU, 61 GB RAM)

• Three load test runners (for running the loadtest)

• Three NGINX proxies