You can configure Mattermost as a high availability cluster-based deployment 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-based 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 cluster-based 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#

Also available in legacy Mattermost 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#

Also available in legacy Mattermost Enterprise Edition E20

The cluster to join by name in a high availability cluster-based deployment.

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#

Also available in legacy Mattermost 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-based deployment documentation for details.

Use IP address#

Also available in legacy Mattermost Enterprise Edition E20

You can configure your high availability cluster-based deployment 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

Enable experimental gossip encryption#

Also available in legacy Mattermost 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#

Also available in legacy Mattermost 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#

Also available in legacy Mattermost 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

Read only config#

Also available in legacy Mattermost 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#

Also available in legacy Mattermost Enterprise Edition E20

An IP address used to identify the device that does automatic IP detection in high availability cluster-based deployments.

String input.

  • System Config path: N/A

  • config.json setting: ".ClusterSettings.NetworkInterface: "",

  • Environment variable: MM_CLUSTERSETTINGS_NETWORKINTERFACE

Bind address#

Also available in legacy Mattermost 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