Rolling Upgrades for High Availability Mattermost Deployments

Stu Doherty

Updated August 28, 2025 13:54

Problem

Organizations running High Availability Mattermost deployments need to upgrade their servers without experiencing downtime or service interruptions for users.

For these organizations requirements may or may not include:

Need to upgrade Mattermost version without service downtime
Users must remain connected during upgrade process
High availability deployment with multiple nodes and load balancer
Configuration stored in database (not file-based config.json)

Solution

Use the rolling upgrade approach to upgrade each Mattermost node individually while maintaining service availability. The load balancer automatically handles traffic routing based on service health.

Prerequisites

High Availability Mattermost deployment with multiple server nodes
Load balancer configured to distribute traffic across nodes
Configuration stored in database (not file-based config.json)
- See Configuration in Your Database
Mattermost version 8.1 or later

Supported Upgrade Paths

Non-ESR Upgrades: Adjacent minor version upgrades (e.g., 9.1 → 9.2, 9.2 → 9.3)

ESR Upgrades: Extended Support Release to next ESR (e.g., ESR 9.5 → ESR 10.1)

Rolling Upgrade Process Steps

Shutdown Mattermost on the first node
Load balancer automatically detects the service is down and stops routing requests to that node
Upgrade Mattermost on the offline node using your standard upgrade process
Start Mattermost on the upgraded node
Verify the node is healthy and receiving traffic again
Repeat for each remaining node, one at a time

For upgrading individual nodes, follow the Comprehensive Upgrade Guide for your specific installation method.

Key Considerations:

Only upgrade one node at a time
Wait for each node to fully start and rejoin the cluster before proceeding to the next
Verify the load balancer detects the node as healthy before moving to the next node

Database Schema Updates

Database migrations run automatically on the first node to start with the new version
Subsequent nodes will detect the migration has completed
Ensure only one node starts at a time during major version upgrades

Session Management

User sessions remain valid across the upgrade
WebSocket connections may briefly disconnect and reconnect
Users may see brief connection interruptions but won't need to re-login

Load Balancer Requirements

Health checks must be properly configured to detect service availability
Health check endpoint: GET /api/v4/system/ping
Load balancer should automatically remove unhealthy nodes from rotation

Rollback Strategy

If issues are encountered during upgrade, follow your standard rollback procedures for the affected node. The remaining nodes will continue serving traffic.