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.

Indexes to skip while purging

Specify index names to ignore while purging indexes. Separate multiple index names with commas. Use an asterisk (*) to match a sequence of index name characters.

System Config path: Environment > Elasticsearch config.json setting: ElasticsearchSettings.IgnoredPurgeIndexes Environment variable: MM_ELASTICSEARCHSETTINGS_IGNOREDPURGEINDEXES

Purge indexes

Available in legacy Enterprise Edition E10/E20

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 needed before those posts are added to the Elasticsearch index. Once added to the Index, the post becomes searchable. On servers with more than 1 post per second, we suggest setting this value to the average number of posts over a 20 second period of time. Numerical input. Default is 1. Every post is indexed synchronously as they are created.

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 or resource limit of your Elasticsearch cluster on installs handling more than 1 post per second. What exactly happens when I increase this value? The primary impact is that a post will be indexed into Elasticsearch after the threshold of posts is met which then makes the posts searchable within Mattermost. So, if you set this based on our recommendations for larger servers, and you make a post, you cannot find it via search for ~ 10-20 seconds, on average. Realistically, no users should see or feel this impact due to the limited amount of users who are actively searching for a post this quickly. You can set this value to a lower average or higher average as well, depending on your Elasticsearch server specifications. During busy periods, this delay will be faster as more traffic is happening, causing more posts and a quicker time to hit the index number. During slow times, expect the reverse.

How to find the right number for your server

1. You must understand how many posts your server makes every minute. Run the query below to calculate your server’s average posts per minute.

   Note that this query can be heavy, so we recommend that you run it during non-peak hours. Additionally, you can adjust the WHERE clause to see the posts per minute over a different time period. Right now 31536000000 represents the number of milliseconds in a year.

   SELECT
     AVG(postsPerMinute) as averagePostsPerMinute
   FROM (
     SELECT
       count(*) as postsPerMinute,
       date_trunc('minute', to_timestamp(createat/1000))
     FROM posts
     WHERE createAt > ( (extract(epoch from now()) * 1000 )  - 31536000000)
     GROUP BY date_trunc('minute', to_timestamp(createat/1000))
   ) as ppm;
   

2. Decide the acceptable index window for your environment, and divide your average posts per minute by that. We suggest 10-20 seconds. Assuming you have 600 posts per minute on average, and you want to index every 20 seconds (60 seconds / 20 seconds = 3`) you would calculate 600 / 3 to come to the number 200. After 200 posts, Mattermost will index the posts into Elasticsearch. So, on average, there would be a 20-second delay in searchability.

3. Edit the config.json or run mmctl to modify the LiveIndexingBatchSize setting

   In the ``config.json``

   {
     "ElasticsearchSettings": {
       "LiveIndexingBatchSize": 200
     }
   }
   

   Via mmctl

   mmctl config set ElasticsearchSettings.LiveIndexingBatchSize 200
   

   Via an environment variable

   MM_ELASTICSEARCHSETTINGS_LIVEINDEXINGBATCHSIZE = 200
   

4. Restart the Mattermost server.

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