upstream-mattermost/docs/main/deployment-guide/scale/elasticsearch-setup.mdx

---
title: "Elasticsearch server setup"
---
import Inc0_common_configure_mattermost_for_enterprise_search from './common-configure-mattermost-for-enterprise-search.mdx';

<PlanAvailability slug="ent-plus" />

Elasticsearch allows you to search large volumes of data quickly, in near real-time, by creating and managing an index of post data. The indexing process can be managed from the System Console after setting up and connecting an Elasticsearch server. The post index is stored on the Elasticsearch server and updated constantly after new posts are made. In order to index existing posts, a bulk index of the entire post database must be generated.

Deploying Elasticsearch includes the following two steps: [setting up Elasticsearch](#set-up-elasticsearch), and [configuring Mattermost](#configure-mattermost).

## Set up Elasticsearch

We highly recommend that you set up Elasticsearch server on a dedicated machine separate from the Mattermost Server.

1.  Download and install the latest release of [Elasticsearch v9](https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html) or [Elasticsearch v8](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/install-elasticsearch.html). See the Elasticsearch documentation for installation details.
2.  Set up Elasticsearch with `systemd` by running the following commands:

> ``` sh
> sudo /bin/systemctl daemon-reload
> sudo /bin/systemctl enable elasticsearch.service
> sudo systemctl start elasticsearch.service
> ```

3.  Confirm Elasticsearch is working on the server by running the following command:

> ``` sh
> curl localhost:9200
> ```

4.  Get your network interface name by running the following command:

> ``` sh
> ip addr
> ```

5.  Edit the Elasticsearch configuration file in `vi` by running the following command:

> ``` sh
> vi /etc/elasticsearch/elasticsearch.yml
> ```

6.  In this file, replace the `network.host` value of `_eth0_` with your network interface name, and save your changes.
7.  Ensure you set `action.destructive_requires_name` to `false` in `elasticsearch.yml` to allow for wildcard operations to work.
8.  Restart Elasticsearch by running the following commands:

> ``` sh
> sudo systemctl stop elasticsearch
> sudo systemctl start elasticsearch
> ```

9.  Confirm the ports are listenings by running the following command:

> ``` sh
> netstat -plnt
> ```
>
> You should see the following ports, including the ones listening on ports 9200 and 9300. Confirm these are listening on your server's IP address.

10. Create an Elasticsearch directory and give it the proper permissions.
11. Install the [icu-analyzer plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-icu.html) to the `/usr/share/elasticsearch/plugins` directory by running the following command:

> <Important>
>
> The `analysis-icu` plugin is **required on every node in the cluster**, not optional. Mattermost's post and file index templates depend on it. Without the plugin, Mattermost cannot create these templates.
>
> </Important>
>
> ``` sh
> sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
> ```
>
> Restart Elasticsearch on each node to load the newly installed plugin before verifying it; `_cat/plugins` only reports active plugins, so a restart is required first. For production clusters, restart nodes one at a time (rolling restart) rather than all at once. Confirm the plugin is installed and active on every node before continuing. Replace `<your-elasticsearch-host>` and `<password>`, and update the CA path if needed:
>
> ``` sh
> curl --silent --show-error --fail-with-body --cacert /etc/elasticsearch/certs/http_ca.crt --user 'elastic:<password>' 'https://<your-elasticsearch-host>:9200/_cat/plugins?v&h=name,component,version&s=name,component'
> ```
>
> Running this command should show `analysis-icu` once per node in the cluster. If the `analysis-icu` line is missing for any node, the plugin is not installed there. Use plain HTTP without credentials only for a cluster where Elasticsearch security has been explicitly disabled.
>
> **(Optional) CJK language analyzer plugins**: To improve search for Korean, Japanese, or Chinese content, install one or more of the following language-specific analyzer plugins: `analysis-nori` (Korean), `analysis-kuromoji` (Japanese), and `analysis-smartcn` (Chinese).
>
> ``` sh
> sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-nori
> sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-kuromoji
> sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-smartcn
> ```
>
> After installing the CJK plugins, restart Elasticsearch to load them:
>
> ``` sh
> sudo systemctl restart elasticsearch
> ```
>
> Then enable the [EnableCJKAnalyzers](/administration-guide/configure/environment-configuration-settings#enable-cjk-analyzers) configuration setting. See [Enabling Chinese, Japanese, and Korean Search](/administration-guide/configure/enabling-chinese-japanese-korean-search) for additional CJK search configuration options.
>
> <div class="important">
>
> <div class="title">
>
> Important
>
> </div>
>
> If you enable CJK analyzers on a server with existing indexed content, you must purge and rebuild the search index in **System Console \> Environment \> Elasticsearch** for the CJK analyzers to take effect on existing posts.
>
> </div>

12. Test the connection from Mattermost to Elasticsearch by running the following command:

> ``` sh
> curl 172.31.80.220:9200
> ```

## Configure Mattermost

Follow these steps to configure Mattermost to use your Elasticsearch server and to generate the post index:

1.  Go to **System Console \> Environment \> Elasticsearch**.
2.  Set **Enable Elasticsearch Indexing** to `true` to enable the other the settings on the page. Once the configuration is saved, new posts made to the database are automatically indexed on the Elasticsearch server.
3.  Ensure **Backend type** is set to `elasticsearch`.

<Inc0_common_configure_mattermost_for_enterprise_search />