You can configure Mattermost as a high availability environment by going to System Console > Environment > High Availability, or by editing the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.

In a Mattermost high availability cluster deployment, the System Console is set to read-only, and settings can only be changed by editing the config.json file directly. However, to test a high availability environment, you can disable ClusterSettings.ReadOnlyConfig in the config.json file by setting it to false. This allows changes applied using the System Console to be saved back to the configuration file.

Enable high availability mode

Available in legacy Enterprise Edition E20

You can enable high availability mode.

true: The Mattermost server will attempt inter-node communication with the other servers in the cluster that have the same cluster name. This sets the System Console to read-only mode to keep the servers’ config.json files in sync.
false: (Default) Mattermost high availability mode is disabled.

System Config path: Environment > High Availability
config.json setting: ".ClusterSettings.Enable",
Environment variable: MM_CLUSTERSETTINGS_ENABLE

Cluster name

Available in legacy Enterprise Edition E20

The cluster to join by name in a high availability environment.

Only nodes with the same cluster name will join together. This is to support blue-green deployments or staging pointing to the same database.

System Config path: Environment > High Availability
config.json setting: ".ClusterSettings.ClusterName",
Environment variable: MM_CLUSTERSETTINGS_CLUSTERNAME

Override hostname

Available in legacy Enterprise Edition E20

You can override the hostname of this server.

This property can be set to a specific IP address if needed; however, we don’t recommend overriding the hostname unless it’s necessary.
If left blank, Mattermost attempts to get the hostname from the operating system or uses the IP address.

System Config path: Environment > High Availability
config.json setting: ".ClusterSettings.OverrideHostname",
Environment variable: MM_CLUSTERSETTINGS_OVERRIDEHOSTNAME

See the high availability cluster documentation for details.

Use IP address

Available in legacy Enterprise Edition E20

You can configure your high availability environment to communicate using the hostname instead of the IP address.

true: (Default) The cluster attempts to communicate using the IP address specified.
false: The cluster attempts to communicate using the hostname.

System Config path: Environment > High Availability
config.json setting: ".ClusterSettings.UseIPAddress: true",
Environment variable: MM_CLUSTERSETTINGS_USEIPADDRESS

Use gossip

Available in legacy Enterprise Edition E20

All cluster traffic uses the gossip protocol.

true: (Default) The server attempts to communicate via the gossip protocol over the gossip port specified.
false: The server attempts to communicate over the streaming port.

System Config path: Environment > High Availability
config.json setting: ".ClusterSettings.UseExperimentalGossip: true",
Environment variable: MM_CLUSTERSETTINGS_USEEXPERIMENTALGOSSIP

Notes:

From Mattermost Server v5.36, gossip clustering can no longer be disabled.
The gossip port and gossip protocol are used to determine cluster health even when this setting is set to false.

Enable experimental gossip encryption

Available in legacy Enterprise Edition E20

Gossip encryption uses AES-256 by default, and this value isn’t configurable by design.

true: (Default for Cloud deployments) All communication through the cluster using the gossip protocol will be encrypted.
false: (Default for self-hosted deployments) All communication using gossip protocol remains unchanged. protocol remains unencrypted.

System Config path: Environment > High Availability
config.json setting: ".ClusterSettings.EnableExperimentalGossipEncryption: false”,
Environment variable: MM_CLUSTERSETTINGS_ENABLEEXPERIMENTALGOSSIPENCRYPTION

Note: Alternatively, you can manually set the ClusterEncryptionKey row value in the Systems table. A key is a byte array converted to base64. Set this value to either 16, 24, or 32 bytes to select AES-128, AES-192, or AES-256 respectively.

Enable gossip compression

Available in legacy Enterprise Edition E20

Once all servers in a cluster are upgraded to Mattermost v5.33 or later, we recommend that you disable this configuration setting for better performance.

true: (Default for self-hosted deployments) All communication through the cluster uses gossip compression. This setting is enabled by default to maintain compatibility with older servers.
false: (Default for Cloud deployments) All communication using the gossip protocol remains uncompressed.

System Config path: Environment > High Availability
config.json setting: ".ClusterSettings.EnableGossipCompression: true”,
Environment variable: MM_CLUSTERSETTINGS_ENABLEGOSSIPCOMPRESSION

Gossip port

Available in legacy Enterprise Edition E20

The port used for the gossip protocol. Both UDP and TCP should be allowed on this port.

Numerical input. Default is 8074.

System Config path: Environment > High Availability
config.json setting: ".ClusterSettings.GossipPort: 8074”,
Environment variable: MM_CLUSTERSETTINGS_GOSSIPPORT

Streaming port

Available in legacy Enterprise Edition E20

The port used for streaming data between servers.

Numerical input. Default is 8075.

System Config path: Environment > High Availability
config.json setting: ".ClusterSettings.StreamingPort: 8075",
Environment variable: MM_CLUSTERSETTINGS_STREAMINGPORT

Read only config

Available in legacy Enterprise Edition E20

true: (Default) Changes made to settings in the System Console are ignored.
false: Changes made to settings in the System Console are written to config.json.

System Config path: N/A
config.json setting: ".ClusterSettings.ReadOnlyConfig: true,
Environment variable: MM_CLUSTERSETTINGS_READONLYCONFIG

Network interface

Available in legacy Enterprise Edition E20

An IP address used to identify the device that does automatic IP detection in high availability clusters.

String input.

System Config path: N/A
config.json setting: ".ClusterSettings.NetworkInterface: "",
Environment variable: MM_CLUSTERSETTINGS_NETWORKINTERFACE

Bind address

Available in legacy Enterprise Edition E20

An IP address used to bind cluster traffic to a specific network device.

This setting is used primarily for servers with multiple network devices or different Bind Address and Advertise Address like in deployments that involve NAT (Network Address Translation).

String input.

System Config path: N/A
config.json setting: ".ClusterSettings.BindAddress: "",
Environment variable: MM_CLUSTERSETTINGS_BINDADDRESS

Advertise address

Available in legacy Enterprise Edition E20

The IP address used to access the server from other nodes. This settings is used primary when cluster nodes are not in the same network and involve NAT (Network Address Translation).

String input.