Elasticsearch provides enterprise-scale deployments with optimized search performance and prevents performance degradation and timeouts. Learn more about Elasticsearch in our product documentation.

You can configure the Elasticsearch environment in which Mattermost is deployed in System Console > Environment > Elasticsearch. You can also edit the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.

Enable Elasticsearch indexing 

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to index new posts automatically.

  • true: Indexing of new posts occurs automatically.

  • false: (Default) Elasticsearch indexing is disabled and new posts are not indexed.

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.EnableIndexing: false",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_ENABLEINDEXING

Notes:

  • If indexing is disabled and re-enabled after an index is created, we recommend you purge and rebuild the index to ensure complete search results.

  • Search queries will use database search until Elasticsearch for search queries is enabled.

Server connection address 

Available in legacy Enterprise Edition E10/E20

The address of the Elasticsearch server.

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.ConnectionUrl",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_CONNECTIONURL

CA path 

Optional path to the Custom Certificate Authority certificates for the Elasticsearch server.

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.CA",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_CA

Note: Available from Mattermost v7.8. Can be used in conjunction with basic auth credentials or to replace them. Leave this setting blank to use the default Certificate Authority certificates for the operating system.

Client certificate path 

Optional client certificate for the connection to the Elasticsearch server in the PEM format.

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.ClientCert",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_CLIENTCERT

Note: Available from Mattermost v7.8. Can be used in conjunction with basic auth credentials or to replace them.

Client certificate key path 

Optional key for the client certificate in the PEM format.

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.ClientKey",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_CLIENTKEY

Note: Available from Mattermost v7.8. Can be used in conjunction with basic auth credentials or to replace them.

Skip TLS verification 

Available in legacy Enterprise Edition E10/E20

The certificate step for TLS connections can be skipped.

  • true: Skips the certificate verification step for TLS connections.

  • false: (Default) Mattermost does not skip certificate verification.

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.SkipTLSVerification: false",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_SKIPTLSVERIFICATION

Server username 

Available in legacy Enterprise Edition E10/E20

(Optional) The username to authenticate to the Elasticsearch server.

String input.

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.UserName",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_USERNAME

Server password 

Available in legacy Enterprise Edition E10/E20

(Optional) The password to authenticate to the Elasticsearch server.

String input.

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.Password",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_PASSWORD

Enable cluster sniffing 

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to automatically find and connect to all data nodes in a cluster.

  • true: Sniffing finds and connects to all data nodes in your cluster automatically.

  • false: (Default) Cluster sniffing is disabled.

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.Sniff: false",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_SNIFF

Select the Test Connection button in the System Console to validate the connection between Mattermost and the Elasticsearch server.

Bulk indexing 

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to start a bulk index of all existing posts in the database.

  • System Config path: Environment > Elasticsearch

  • config.json setting: N/A

  • Environment variable: N/A

Select the Index Now button in the System Console to start a bulk index of all posts. If the indexing process is canceled, the index and search results will be incomplete.

Purge indexes 

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to purge the entire Elasticsearch index. Typically only used if the index has corrupted and search isn’t behaving as expected.

  • System Config path: Environment > Elasticsearch

  • config.json setting: N/A

  • Environment variable: N/A

Select the Purge Indexes button in the System Console to purge the index. After purging the index, create a new index by selecting the Index Now button.

Enable Elasticsearch for search queries 

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to use Elasticsearch for all search queries using the latest index

  • true: Elasticsearch will be used for all search queries using the latest index. Search results may be incomplete until a bulk index of the existing post database is finished.

  • false: (Default) Database search is used for search queries.

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.EnableSearching: false",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_ENABLESEARCHING

Enable Elasticsearch for autocomplete queries 

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to use Elasticsearch for all autocompletion queries on users and channels using the latest index.

  • true: Elasticsearch will be used for all autocompletion queries on users and channels using the latest index.

  • false: (Default) Database autocomplete is used.

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.EnableAutocomplete: false",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_ENABLEAUTOCOMPLETE

Note: Autocompletion results may be incomplete until a bulk index of the existing users and channels database is finished.

Post index replicas 

Available in legacy Enterprise Edition E10/E20

The number of replicas to use for each post index.

Numerical input. Default is 1.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.PostIndexReplicas: 1",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_POSTINDEXREPLICAS

Important note: If this setting is changed, the changed configuration only applies to newly-created indexes. To apply the change to existing indexes, purge and rebuild the index after changing this setting.

Post index shards 

Available in legacy Enterprise Edition E10/E20

The number of shards to use for each post index.

Numerical input. Default is 1.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.PostIndexShards: 1",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_POSTINDEXSHARDS

Important note: If this setting is changed, the changed configuration only applies to newly-created indexes. To apply the change to existing indexes, purge and rebuild the index after changing this setting.

Channel index replicas 

Available in legacy Enterprise Edition E10/E20

The number of replicas to use for each channel index.

Numerical input. Default is 1.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.ChannelIndexReplicas: 1",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_CHANNELINDEXREPLICAS

Channel index shards 

Available in legacy Enterprise Edition E10/E20

The number of shards to use for each channel index.

Numerical input. Default is 1.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.ChannelIndexShards: 1",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_CHANNELINDEXSHARDS

User index replicas 

Available in legacy Enterprise Edition E10/E20

The number of replicas to use for each user index.

Numerical input. Default is 1.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.UserIndexReplicas: 1",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_USERINDEXREPLICAS

User index shards 

Available in legacy Enterprise Edition E10/E20

The number of shards to use for each user index.

Numerical input. Default is 1.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.UserIndexShards: 1",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_USERINDEXSHARDS

Aggregate search indexes 

Available in legacy Enterprise Edition E10/E20

Elasticsearch indexes older than the age specified by this setting, in days, will be aggregated during the daily scheduled job.

Numerical input. Default is 365 days.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.AggregatePostsAfterDays: 365",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_AGGREGATEPOSTSAFTERDAYS

Note: If you’re using data retention and Elasticsearch, configure this with a value greater than your data retention policy.

Post aggregator start time 

Available in legacy Enterprise Edition E10/E20

The start time of the daily scheduled aggregator job.

Must be a 24-hour time stamp in the form HH:MM based on the local time of the server.

Default is 03:00 (3 AM)

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.PostsAggregatorJobStartTime: 03:00",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_POSTSAGGREGATORJOBSTARTTIME

Index prefix 

Available in legacy Enterprise Edition E10/E20

The prefix added to the Elasticsearch index name.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.IndexPrefix",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_INDEXPREFIX

Note: When this setting is used, all Elasticsearch indexes created by Mattermost are given this prefix. You can set different prefixes so that multiple Mattermost deployments can share an Elasticsearch cluster without the index names colliding.

Live indexing batch size 

Available in legacy Enterprise Edition E10/E20

The number of new posts batched together before they’re added to the Elasticsearch index.

Numerical input. Default is 1.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.LiveIndexingBatchSize: 1",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_LIVEINDEXINGBATCHSIZE

Note: It may be necessary to increase this value to avoid hitting the rate limit of your Elasticsearch cluster on installs handling multiple messages per second.

Bulk indexing time window 

Available in legacy Enterprise Edition E10/E20

The maximum time window, in seconds, for a batch of posts being indexed by the Bulk Indexer. This setting serves as a performance optimization for installs with over ~10 million posts in the database.

Numerical input in seconds. Default is 3600 seconds (1 hour). Approximate this value based on the average number of seconds for 2,000 posts to be added to the database on a typical day in production.

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.BulkIndexingTimeWindowSeconds: 3600",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_BULKINDEXINGTIMEWINDOWSECONDS

Note: Setting this value too low will cause bulk indexing jobs to run slowly.

Request timeout 

Available in legacy Enterprise Edition E10/E20

The timeout, in seconds, for Elasticsearch calls.

Numerical input in seconds. Default is 30 seconds.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.RequestTimeoutSeconds :30",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_REQUESTTIMEOUTSECONDS

Trace 

Available in legacy Enterprise Edition E10/E20

Options for printing Elasticsearch trace errors.

  • error: Creates the error trace when initializing the Elasticsearch client and prints any template creation or search query that returns an error as part of the error message.

  • all: Creates the three traces (error, trace and info) for the driver and doesn’t print the queries because they will be part of the trace log level of the driver.

  • not specified: (Default) No error trace is created.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.Trace",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_TRACE