Mattermost high availability guide

When Mattermost high availability is worth the added complexity

Mattermost high availability is a clustered design, not a second server beside the first. It requires the Enterprise or Enterprise Advanced plan, shared file storage on Amazon S3, an S3-compatible service or NAS mounted on every node, and a database layer that can fail over. If your team is running Mattermost for business communication and now needs it to keep working through a node or database failure, the decision is less about whether you want redundancy and more about whether your organization can operate the extra moving parts that redundancy requires.

Adding a second application server is the easy part. The harder work is making each component behave correctly when one node disappears in the middle of a session. User sessions must be valid on any app node, so a failed node does not force every user to sign in again or lose unsent work. Uploaded files must be readable from every node through the shared object store or NAS, because local file system storage will not work correctly in a cluster and risks corrupting files. Search must keep returning results when the node or replica that served the last query is gone. Database failover must promote a replica and redirect connections without leaving the application writing to a database that is no longer primary.

Each of these behaviors needs a deliberate check rather than an assumption. Ask your platform or database team who owns the shared storage service, what its own availability target is, and whether its failure would take down Mattermost even if every app node stayed healthy. Confirm with your database provider how failover is triggered, how long client connections take to reconnect, and whether the application can reach the new primary without manual configuration. The Mattermost high availability documentation describes read replicas for scaling concurrent users and search replicas for query load, with writes always sent to the primary, so you should confirm which of your workloads actually need those replicas.

The licensing decision comes first. Mattermost sells high availability clustering only on the Enterprise and Enterprise Advanced plans, and the subscription is based on seat licenses. Confirm current plan terms and pricing directly with Mattermost, since the public pricing page lists no prices and directs buyers to sales. If your user base is small, your recovery objectives are modest, or a planned restore from backup would be acceptable to the business, a single well-backed-up deployment may be the better trade-off. If messaging is a dependency for incident response or regulated operations, the added licensing, storage and operations cost is easier to justify.

Plan the test before you commit. A cluster that has never been deliberately broken is an assumption, not a design. Before go-live, schedule a controlled node stop, a database primary failover and a storage outage, and record what users see, how long recovery takes, and which alerts fire. Decide who runs these tests and how often they repeat after each upgrade. Those results, together with the storage and database costs you have confirmed, tell you whether the added complexity is worth carrying for your organization.

Which Mattermost components need redundancy

A Mattermost high availability cluster is built from a small set of components, and each one must survive a failure without taking the others down. Mattermost is a single Linux binary backed by PostgreSQL, so the cluster design is largely about running several copies of that binary against shared, redundant data services.

Redundant application servers

Mattermost runs as a single Linux binary, so high availability means running two or more identical application nodes that all serve the same database and file storage. If one node fails, the remaining nodes keep serving users. Check that every node is built from the same server version and configuration, because mismatched nodes are a common source of hard-to-diagnose faults.

Redundant database servers

Mattermost stores its data in PostgreSQL, and the database is the single source of truth for messages, channels and users. Without a redundant primary and failover arrangement, a database outage stops the whole cluster even when every application node is healthy. Confirm the failover approach, the replication mode and how the application reconnects after a switchover with your database team.

Redundant load balancers

Users and clients reach the cluster through a load balancer that spreads connections across the application nodes and removes unhealthy ones from rotation. A single load balancer would reintroduce a single point of failure in front of an otherwise redundant cluster. Verify health checks, session handling and TLS termination on each load balancer, and test a failover of the balancer itself.

Shared file storage on Amazon S3 or NAS

Each node must read and write uploaded files from the same shared store, which can be Amazon S3, an S3-compatible service or a NAS mounted on every node. Local file system storage does not work correctly in a cluster and risks corrupting files. Confirm that the shared store is itself highly available and backed up, since losing it loses user files even when every server is healthy.

Database read replicas

Read replicas let Mattermost distribute read queries across additional PostgreSQL copies while writes continue to go to the primary database. They protect performance under heavy concurrent use and reduce latency for read-heavy work, rather than providing failover on their own. Ask which read paths the replicas serve, how replication lag is monitored, and what users see when a replica falls behind.

Database search replicas

Search replicas are a separate replica type that Mattermost can use for search queries, keeping search load away from the primary database. They matter most in larger teams where search activity competes with messaging traffic. Confirm that search replicas are supported in your planned Mattermost version and plan, and test search results and freshness after a replica or primary failure.

Decisions to settle before building the cluster

This table compares the four main design choices for a Mattermost high availability cluster and what each one costs to run. Read each row as a decision: find the option that fits your staffing and hosting model, then confirm the vendor and environment specifics before committing. The main takeaway is that the operational burden of the cluster sits mostly in database failover, shared file storage and failure testing, so settle those first.

Decision	Option A	Option B	Operational cost to weigh
Application server hosting	Bare Linux nodes behind a load balancer. Fits teams already running Linux fleets with configuration management and a clear patching process.	Containers on an orchestrator. Fits teams with container platform skills and an existing cluster to host Mattermost, including a Kubernetes route covered separately.	Bare nodes add OS patching and config drift control. Containers add image rebuilds and orchestrator upkeep. Confirm which your platform team already supports.
PostgreSQL high availability	Self-managed primary with standby failover. Fits teams with strong database operations and a tested failover runbook.	Managed database service from a cloud provider. Fits teams that prefer a vendor to handle replication, backups and minor patching.	Self-managed needs replication monitoring, backup restore tests and failover drills. Managed shifts some work to the provider but adds dependency on its maintenance windows and failover behavior. Confirm the exact options in your provider.
Shared file storage	Amazon S3 or an S3-compatible service. Fits deployments already on AWS or an object store with reliable access from every node.	NAS mounted on each node. Fits organizations with an existing NAS platform and network performance to match.	S3 needs credential rotation, bucket policies and egress planning. NAS needs mount monitoring, capacity growth and storage vendor support. Local disk is not an option for a cluster.
Read and search replicas	Add now. Fits large expected user counts or heavy search use from the start, and needs replica monitoring from day one.	Add later. Fits pilots and smaller first phases, provided the database layer can accept replicas without redesign.	Replicas add database instances to patch, monitor and fail over. Confirm replica support and sizing guidance with Mattermost for your server version.

How to build a Mattermost HA cluster in order

This sequence takes a Mattermost deployment from a licensing check to a cluster where any node can serve any user and file, with each step closed by a verifiable check. Follow the order, because later steps depend on the database, shared storage and identical nodes built before them.

Confirm the license and seat count
Before any build work, confirm that the plan includes high availability clustering. Mattermost lists HA clustering from the Enterprise plan and documents high availability as available only on Enterprise and Enterprise Advanced. Confirm the seat count against the expected number of active users, and confirm with Mattermost sales how the subscription is activated on your servers. Done when the subscription covers the Enterprise or Enterprise Advanced plan, the seat count is written into the scope, and the license file or activation method is recorded for the build team.
Provision the PostgreSQL primary and standby
Build the PostgreSQL primary that every application node will write to, and set up a standby with a documented promotion path so a database failure has a known recovery route. The database team owns the replication setup, backup schedule and failover runbook. Confirm the PostgreSQL versions supported for your Mattermost release in the high availability docs before provisioning. Done when a test write on the primary appears on the standby and the failover runbook has been walked through once with the operations team.
Mount shared file storage on every node
Provision Amazon S3, an S3-compatible service or NAS that every application node can reach, and mount or configure it identically on each node. Local file system storage will not work correctly in a cluster and risks corrupting files, so do not use node-local disks for uploads. Confirm the exact file storage configuration keys for your version in the high availability documentation rather than relying on older guides. Done when a file uploaded through one node can be read and downloaded through every other node.
Install identical Mattermost application nodes
Install the same Mattermost server version on each application node, using the same configuration file, the same license, and the same connection settings for the database and file storage. Keep the configuration in version control so that nodes cannot drift apart. Confirm the cluster settings and the discovery method in the high availability docs for your version. Done when every node reports the same server version, starts cleanly, and appears as a member of the cluster in the system console.
Configure the load balancer and health checks
Place a redundant pair of load balancers in front of the application nodes, and configure health checks that remove a node from rotation when it stops responding. Terminate TLS at the load balancer or reverse proxy according to your security standard, and confirm the health check endpoint and the session affinity behavior in the high availability docs. Redundant load balancers are part of the Mattermost high availability architecture, so the pair itself must also fail over. Done when a node stopped on purpose is removed from rotation and users continue to reach the service through the others.
Add read and search replicas if needed
Add database read replicas and search replicas only when the expected concurrent load justifies them. Mattermost distributes reads across replicas and sends writes to the primary, so replicas help scale concurrent users and reduce latency. Confirm replica configuration keys and replication lag expectations for your version in the docs, and monitor lag once replicas are live. This step is optional for smaller deployments. Done when reads are visibly served from replicas in the monitoring data and writes still land on the primary.
Test sessions and file access from every node
Test the cluster from every application node, not only through the load balancer. Sign in, send messages, post files, edit a channel, and confirm that real-time updates arrive across sessions connected to different nodes. Then stop one node during an active session and confirm the user reconnects without data loss. Record the results and repeat the test after every upgrade or configuration change. Done when session behavior and file access are consistent from all nodes and the failover test is documented.

What drives the cost and effort of a Mattermost HA build

This table lists the factors that change the scope of a Mattermost high availability build and the effort each one adds. Read each row as a question to answer before requesting a fixed-scope quote, because the same architecture can be small or large depending on these inputs. The main takeaway is that the decisions made early on user load, file storage and identity integration set most of the work.

Driver	How it raises effort	How to keep it down
Concurrent user count	Higher concurrency drives more app server nodes, read replicas and load testing before go-live. Sizing has to be confirmed with real peak figures, not headcount alone.	Get peak concurrent user numbers from your own usage data, and agree which load tests are in scope before the quote is set.
File volume and retention	Large attachment volumes and long retention periods increase storage design, backup scope, restore testing and migration of existing files.	Define file size limits, retention periods and legal hold needs early, and confirm whether historical files must be migrated.
Shared storage choice (S3 or NAS)	Each node must mount the same shared store, so NAS mounts, S3 credentials, endpoints and encryption settings each add configuration and validation. Local storage is not supported for HA.	Pick the storage type your team already operates and can back up, and confirm the S3-compatible service works with Mattermost before design starts.
Database topology and failover method	A primary with read and search replicas, plus a chosen failover approach, adds replication setup, connection handling and failover testing for each scenario.	Use the database platform your organization already runs, and limit the failover scenarios to those your recovery objectives require.
Load balancer and network constraints	Health checks, session handling, TLS termination, firewall rules and cross-zone routing require coordination with network and security teams, which often takes the longest.	Document the existing load balancer, network zones and change approval steps, and confirm them with the network team before design.
Number of environments	Each extra environment (test, staging, production, disaster recovery) repeats build, configuration, data handling and testing work.	Agree which environments are needed and whether non-production can run at a smaller size, and state this in the written scope.
SSO and identity integration	Connecting SAML, OIDC or AD/LDAP, group sync and provisioning rules adds identity configuration and testing with each identity provider. SSO is available from the Professional plan, while HA requires Enterprise or Enterprise Advanced.	Confirm the identity provider, the groups to sync and who owns the identity configuration before the build starts.
Compliance evidence needs	Assessors may ask for configuration records, access reviews, backup and restore results, failover test records and change logs. Producing this evidence adds documentation and testing effort. DeployOpen prepares evidence but does not issue audit reports.	Ask your auditor which evidence they expect and include it as a deliverable in the written scope, so it is not added later.

How the HA design changes by environment

A single node runs the Mattermost server and PostgreSQL on one host. It suits evaluation or a small team that can accept downtime during repairs and upgrades. Because no cluster is built, the shared storage and multi-node load balancing requirements do not apply in the same way.

Storage: Files are kept on the host's local file system. Shared S3 or NAS storage becomes necessary only when a second application server joins the cluster.
Load balancing: No cluster load balancer is needed. Users connect to one address, usually through a reverse proxy that your team manages.
Database failover: No replica or standby exists. Recovery depends on restoring PostgreSQL from backup, so confirm the backup schedule and a tested restore procedure before go-live.
Upgrades: Each upgrade requires a maintenance window on the only server. Check the release notes for the target version and take a backup first.

Before choosing this model, confirm that the team can tolerate the outage risk and that a later move to a cluster is planned, because the storage and database layout will change at that point.

Securing the cluster's shared components

A high availability Mattermost cluster shares state across several nodes: one file store, one PostgreSQL primary with replicas, and a load balancer in front. Each shared component adds an access path that an attacker or a misconfigured node could use, so the controls below should be designed before the cluster goes live.

Restricting access to the shared file store

Every application node reads and writes attachments and uploads through the same Amazon S3 bucket, S3-compatible service or NAS export. Scope each node's credentials or mount permissions to that one bucket or export, deny public access, and confirm that object versioning, encryption at rest and access logging are set as your policy requires. Test that a node outside the cluster cannot list or read the store.

Managing database credentials across nodes

Application nodes, read replicas and search replicas each hold connection strings to PostgreSQL. Store these in a secrets manager or restricted configuration source, not in plain text files copied to each server. Use separate database roles for the primary and for replica connections where the engine supports it, and plan how a credential rotation reaches every node without a full outage.

Protecting load balancer TLS certificates

The load balancer terminates TLS for users, so its private keys are one of the most valuable secrets in the cluster. Limit who can read or export the key, keep it out of shared repositories, and record who holds renewal rights. Confirm how certificate renewal is performed on every load balancer node, since a missed renewal on one node can break client connections intermittently.

Limiting administrative access to cluster configuration

Shared configuration determines how every node behaves, so changes to it are a cluster-wide risk. Restrict who can edit the configuration file or environment settings, require review for changes, and keep an audit trail of who changed what and when. Separate the people who run upgrades from those who manage user administration, and confirm that the Mattermost admin console permissions match that split.

Keeping replica access separate from the primary

Read and search replicas serve queries, but they still hold a full copy of message data. Restrict network paths so that only the application nodes can reach replica ports, use read-only database roles on replicas where possible, and avoid giving replica credentials write or administrative rights. Document which node types connect to which database endpoint so that a compromised replica cannot be used to reach the primary.

How to test that Mattermost fails over safely

A failover test is only useful if you have written down what a safe failure looks like before you break anything. For a Mattermost high availability cluster, safe means four things: users reconnect without manual intervention, no posted message or uploaded file is lost, the promoted database becomes the write target, and read and search traffic keeps being served by the replicas that remain. Check each expectation against the official high availability documentation for your Mattermost version, because reconnection behavior, replica routing and search indexing all depend on configuration. Treat the documented behavior as the baseline and record any deviation as a finding that needs an explanation.

Run these tests against a staging copy with the same topology as production, and generate steady activity first: test users posting in several channels, uploading files and searching. Stop one application node during that activity. Confirm that clients reconnect through the load balancer, that messages sent during the outage appear once the node returns, and that no sent message or file is missing. Next, fail the primary PostgreSQL database and confirm that the promoted standby accepts writes and that the application connects to it, using whatever mechanism your database platform uses to redirect traffic. Finally, remove one load balancer node from rotation and check that health checks drain it and that the remaining nodes carry the load without errors.

File storage and search need their own checks because they fail in quieter ways. Upload a file through each application node and download it through every other node, then compare checksums against the originals. This confirms that the shared Amazon S3, S3-compatible or NAS storage is mounted and visible from every node. For search, create a controlled replica lag event in staging, for example by pausing replication for a set period. Post messages during the lag and query them from each node. Record when new messages appear in search results, and confirm that all nodes converge once replication catches up. Confirm with the documentation how search replicas are expected to behave during lag, because that answer determines what users can be told during an incident.

Evidence is what turns a test into a record your security and operations teams can rely on. Before the first run, write pass and fail criteria for each scenario, including the expected reconnection behavior and the longest acceptable delay before new writes are visible to users. During each run, capture timestamps from application and database logs, the node or database involved, client-side observations, message and file checksums, search query outputs, and the Mattermost server version and configuration in use. Store the scripts, results and any screenshots together under change control so that a later reviewer can see what was tested, when, and against which build.

Repeat the full test set after every upgrade, after any change to database topology, storage mounts, load balancer configuration or proxy settings, and before moving a new release into production. Mattermost ships server versions in binary form on a monthly schedule and offers Extended Support Releases for teams that want fewer changes, so the frequency of your test cycle should follow the release track you choose. Keep the test scripts versioned alongside your infrastructure code so the same steps run each time. Treat the outcome as operational evidence for your own assurance process. It does not replace an independent audit or a certification, and it should not be presented as one.

What to monitor, back up and document after go-live

After go-live, a Mattermost cluster stays available only if someone watches its parts, protects its data and keeps its configuration current. The cards below cover the nodes, database, file store and load balancers, plus the backup, release and documentation work that keeps them dependable. Confirm each threshold and schedule with your own platform, database and storage owners.

Node and load balancer health

Track process health, CPU, memory and response times on every Mattermost application node, and check the load balancer's own health probes and backend pool status. A node that stops answering should leave rotation without users noticing, which only happens if the health checks reflect what users need, such as a successful login and a message post. Confirm with your load balancer vendor which check types it supports and how quickly it removes a failed backend. Alert on repeated failures so that single transient errors do not page the on-call team.

Replication status and replica lag

Watch the primary PostgreSQL database for replication state, and watch each read replica and search replica for lag behind the primary. Mattermost sends writes to the primary and distributes reads across replicas, so a lagging replica can show users stale channel or thread views. Agree a lag threshold with your database team, alert when it is exceeded, and confirm how your Mattermost configuration behaves when a replica falls behind. Verify the exact topology against your own PostgreSQL setup.

Shared file store availability

Monitor availability, free capacity and mount health of the Amazon S3, S3-compatible or NAS store that every node uses for uploaded files. Local file system storage is unsupported in a cluster and risks corrupting files, so a mount that drops on one node can produce inconsistent file access across the cluster. Check read and write access from each node on a schedule, track capacity growth against upload trends, and confirm with your storage team how the store handles its own failover.

Backups matched to recovery goals

Back up the PostgreSQL database and the shared file store on schedules set from the recovery point and recovery time objectives agreed with the business. Both must be captured with consistent timing, because a database restored from one point and files restored from another can leave messages pointing at attachments that no longer exist. Test restores into an isolated environment, record how long they take, and keep copies outside the primary failure domain. Confirm retention periods with your compliance owner.

Release cadence and change testing

Mattermost releases server versions in binary form on the 16th of each month. v11.11 was released on 2026-09-16 with support ending 2026-12-15, and v12.0 was released on 2026-10-16 with support ending 2027-01-15. The v11.7 Extended Support Release was released on 2026-05-15 with support ending 2027-05-15. Decide whether each cluster follows the monthly line or stays on an ESR, test each release in staging, and rerun failover tests after every upgrade or configuration change.

Topology, runbooks and named owners

Document the cluster topology, including application nodes, primary and replica database servers, search replicas, load balancers and the file store, with the network paths between them. Write runbooks for node replacement, replica promotion, storage remount and restore, and record the expected sequence and the verification step after each action. Name an owner for each component and an escalation contact outside the platform team. Review the documents after every release and every failover test so they match the running system.

Questions teams ask before building Mattermost high availability

Does Mattermost high availability require an Enterprise plan?

Yes. Mattermost documents high availability as available only on the Enterprise and Enterprise Advanced plans, so a cluster with redundant application servers, database servers and load balancers needs one of those subscriptions. The Mattermost pricing page lists high availability clustering as an Enterprise feature and does not publish prices, so buyers should ask Mattermost sales for current terms. Plans are sold as prepaid annual subscriptions based on seat licenses, which means the license is a recurring cost that sits alongside infrastructure and services. Confirm the plan that matches your user count and compliance needs before you size the rest of the build.

Confirm with Mattermost: the plan, seat count, renewal terms and whether any add-on is required for your deployment.

Can Mattermost high availability use local storage on each node?

No. The Mattermost high availability documentation requires shared file storage on Amazon S3, an S3-compatible service or a NAS mounted on each node. Local file system storage will not work correctly and risks corrupting files, because each application server would hold a different copy of uploaded content. The choice between S3-compatible object storage and NAS depends on what your infrastructure team already operates, the latency between nodes and storage, backup tooling and your data residency rules. Ask your storage team to confirm throughput, snapshot behavior and access controls before committing to either option, and validate file upload and download from every node during testing.

What does a high availability build require from our internal team?

The work spans several skill areas, so the internal team needs owners for each before the build starts. Platform or systems engineers handle load balancers, application servers and the Linux or Kubernetes layer. Database administrators own the PostgreSQL primary, read replicas and search replicas, including replication lag and failover behavior. Storage engineers own the shared S3 or NAS layer, and security staff review TLS, identity integration and access paths. Someone also needs to own change control for the monthly server release train, since each upgrade must be tested across every node. Expect these owners to spend time on design reviews, failure testing and runbooks, not only on installation.

Do we need a partner to build Mattermost high availability?

Not always. A team with experienced PostgreSQL, load balancing and shared storage engineers can build a cluster in-house, provided it has the Enterprise license and time for design and failure testing. A partner becomes useful when those skills are thin, when the deadline is fixed, or when the cluster must be documented and handed over with evidence for an audit or a regulator. DeployOpen plans, implements, hardens, backs up, documents and supports self-hosted platforms inside your own cloud accounts, data centers or air-gapped networks, and most engagements are fixed-scope with a written scope agreed before work starts. Ask any partner to show how it tests node and database failover, not only that the cluster starts.

What drives the cost of a Mattermost high availability build?

Cost has four parts: the Mattermost subscription, infrastructure, people and ongoing operations. The subscription is recurring and priced by seat licenses on the plan you choose. Infrastructure includes application servers, database servers and replicas, load balancers and S3 or NAS capacity, which recur every month. One-time costs include design, configuration, migration of data where applicable, and failure testing. Drivers that raise the total are user count, number of regions, the number of replicas you run, strict compliance controls, and the number of environments such as staging and disaster recovery. Ask any quote to separate one-time services from recurring licensing and infrastructure, and to list assumptions about user count, storage growth and testing scope.

How long does a Mattermost high availability build usually take?

Duration depends on scope, not on a single standard timeline. The biggest drivers are the number of environments, whether storage and identity integration already exist, how many replicas and regions are involved, and how much failure testing and documentation is required. Teams that already run PostgreSQL and shared storage typically move faster than teams building those layers at the same time. Organizations with change-advisory processes or security reviews should add time for approvals. Do not rely on a generic number from any source, including this page. Request a written scope from DeployOpen or any other provider, with milestones, deliverables and the dependencies your side must meet.

Can our team build and test a Mattermost high availability cluster alone?

A capable team can, if it has the Enterprise license, owners for database, storage, load balancing and security, and a test plan that goes beyond the happy path. The hardest part is usually not starting the cluster but proving it behaves correctly during failures: an application node going down, a primary database failover, a replica falling behind, a storage outage and a rolling upgrade. Plan a non-production cluster first, document each failure test with expected results, and repeat tests after every major change. If your team cannot staff those owners or run those tests, a fixed-scope engagement can cover planning, build, testing, documentation and handover.

How DeployOpen scopes, builds and hands over a Mattermost HA cluster

DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside the client's own infrastructure, including Mattermost high availability. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.

How we scope

Confirm the Mattermost edition and license entitlement for high availability before any design work begins.
Map the app server, PostgreSQL primary, read and search replica, load balancer and file storage layout to your environment.
Define the shared S3, S3-compatible or NAS storage option and the network paths each node needs to reach it.

How we build

Deploy redundant application servers, load balancers and database nodes in your cloud accounts, data centers or air-gapped network.
Mount shared file storage on every node and verify that uploads, attachments and exports behave identically across all nodes.
Configure read and search replicas and test failover of application nodes, the primary database and the load balancer.

How we hand over

Provide written runbooks covering node replacement, failover steps, backup and restore, and the upgrade sequence for the cluster.
Deliver the failure test results, configuration records and access model so your team can reproduce and audit the setup.
Walk your operations and security staff through monitoring, alerting and the on-call steps for a cluster node failure.

How we support

Ongoing support, upgrades and continuous testing are available as retainers after handover, scoped in writing.
Plan upgrades on the monthly release train or an Extended Support Release, with cluster-specific rollback steps for each change.
Re-run failure tests after major configuration or version changes so the cluster's recovery behavior stays documented and verified.