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:

  • 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

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

Maximum idle connections for high availability 

Available in legacy Enterprise Edition E20

The maximum number of idle connections held open from one server to all others in the cluster.

Numerical input. Default is 100.

  • System Config path: N/A

  • config.json setting: ".ClusterSettings.MaxIdleConns: 100,

  • Environment variable: MM_CLUSTERSETTINGS_MAXIDLECONNS

Maximum idle connections per host 

Available in legacy Enterprise Edition E20

The maximum number of idle connections held open from one server to another server in the cluster.

Numerical input. Default is 128.

  • System Config path: N/A

  • config.json setting: ".ClusterSettings.MaxIdleConnsPerHost: 128",

  • Environment variable: MM_CLUSTERSETTINGS_MAXIDLECONNSPERHOST

Idle connection timeout 

Available in legacy Enterprise Edition E20

The amount of time, in milliseconds, to leave an idle connection open between servers in the cluster.

Numerical input. Default is 90000.

  • System Config path: N/A

  • config.json setting: ".ClusterSettings.IdleConnTimeoutMilliseconds: 90000",

  • Environment variable: MM_CLUSTERSETTINGS_IDLECONNTIMEOUTMILLISECONDS