---
title: Configuring full-text search
description: Setting up Elasticsearch to search for statuses (authored, favourited, or mentioned), public indexable status, and accounts
aliases:
- /admin/optional/elasticsearch
menu:
  docs:
    weight: 40
    parent: admin
---

Mastodon supports full-text search when Elasticsearch is available. It is strongly recommended to configure this feature.

Mastodon’s full-text search allows logged-in users to find results from:
- public statuses from accounts that opted into appearing in search results
- their own statuses
- their mentions
- their favourites
- their bookmarks
- accounts (display name, usernames and bios)

It deliberately does not allow searching for arbitrary strings in the entire database.

{{< hint style="warning" >}}
Please note that ElasticSearch has significant memory requirements, which can easily outpace those of Mastodon itself.
{{< /hint >}}

## Installing Elasticsearch {#install}

{{< hint style="info" >}}
Mastodon is tested with Elasticsearch version 7 (Which is now end of life). It should support OpenSearch, as well as Elasticsearch versions 8 and 9, but those setups are not officially supported. The install instructions within this documentation relate to Elasticsearch version 7 only.
{{< /hint >}}

Add the official Elasticsearch repository to apt:

```bash
wget -O /usr/share/keyrings/elasticsearch.asc https://artifacts.elastic.co/GPG-KEY-elasticsearch
echo "deb [signed-by=/usr/share/keyrings/elasticsearch.asc] https://artifacts.elastic.co/packages/7.x/apt stable main" > /etc/apt/sources.list.d/elastic-7.x.list
```

Now you can install Elasticsearch:

```bash
apt update
apt install elasticsearch
```

{{< hint style="warning" >}}
**Security warning:** By default, Elasticsearch is supposed to bind to localhost only, i.e. be inaccessible from the outside network. You can check which address Elasticsearch binds to by looking at `network.host` within `/etc/elasticsearch/elasticsearch.yml`. Consider that anyone who can access Elasticsearch can access and modify any data within it, as there is no authentication layer. So it’s really important that the access is secured. Having a firewall that only exposes the 22, 80 and 443 ports is advisable, as outlined in the [main installation instructions](../../prerequisites/#install-a-firewall-and-only-whitelist-ssh-http-and-https-ports). If you have a multi-host setup, you must know how to secure internal traffic.
{{< /hint >}}

Before you start Elasticsearch, you might want to limit its RAM consumption. A RAM limit can be set be creating a new file `/etc/elasticsearch/jvm.options.d/limit-ram.options` with the following content:

```java-properties
# Limit RAM size to 24 GB
-Xms16g
-Xmx24g
```

This will reserve 16 GB of RAM for Elasticsearch right from the start and allow it to use up to 24 GB of RAM. Also see: [Managing and troubleshooting Elasticsearch memory](https://www.elastic.co/blog/managing-and-troubleshooting-elasticsearch-memory/).


{{< hint style="info" >}}
To maximise the performance of your Elasticsearch cluster you should identify a RAM Value which can be sustained and which will not impact other services on the machine you run Elasticsearch on, once identified you should set the `Xms` and `Xmx` values to this value, Elasticsearch will reserve this memory and will always be able to make full use of this memory which in seach heavy situations will improve performance. 
{{< /hint >}}

To start Elasticsearch:

```bash
systemctl daemon-reload
systemctl enable --now elasticsearch
```

## Configuring Mastodon {#config}

Edit `.env.production` to add the following variables:

```bash
ES_ENABLED=true
ES_HOST=localhost
ES_PORT=9200
ES_PRESET= # single_node_cluster, small_cluster or large_cluster
# ES_USER=
# ES_PASS=
```

_Note_: If using TLS, prepend the hostname with `https://`. For example: `https://elastic.example.com`.

### Choosing the correct preset

The value for `ES_PRESET` depends on the size of your Elasticsearch and will be used to set the number of shards and replicas for your indices to the best value for your setup:
- `single_node_cluster` if you only have one node in your Elasticsearch cluster. Indices will be configured without any replica
- `small_cluster` if you have less than 6 nodes in your cluster. Indices will be configured with 1 replica
- `large_cluster` if you have 6 or more nodes in your cluster. Indices will be configured with more shards than with the `small_cluster` setting, to allow them to be distributed over more nodes

If you have multiple Mastodon servers on the same machine, and you are planning to use the same Elasticsearch installation for all of them, make sure that all of them have unique `ES_PREFIX` values configured to differentiate the indices.

### Security

By default, Elasticsearch does not handle any authentication and every request is made with full admin permission. We strongly advise you to configure Elasticsearch security features on your cluster.

To configure it, please refer [to the official documentation](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/security-minimal-setup.html). It will guide you through:
- Enabling the security features (`xpack.security.enabled: true`)
- Creating passwords for built-in users

Once done, you can create a custom role for Mastodon to connect.

For example (please adapt this snippet to use your Elastic admin password):

```sh
curl -X POST -u elastic:admin_password "localhost:9200/_security/role/mastodon_full_access?pretty" -H 'Content-Type: application/json' -d'
{
  "cluster": ["monitor"],
  "indices": [{
    "names": ["*"],
    "privileges": ["read", "monitor", "write", "manage"]
  }]
}
'
```

[Elasticsearch documentation for role creation](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/security-api-put-role.html)

Once the role is created, you can create a user for the Mastodon server to use, and assign it the role.

For example (please adapt this snippet to use your Elastic admin password, and customize your new user `mastodon` user password):

```sh
curl -X POST -u elastic:admin_password "localhost:9200/_security/user/mastodon?pretty" -H 'Content-Type: application/json' -d'
{
  "password" : "l0ng-r4nd0m-p@ssw0rd",
  "roles" : ["mastodon_full_access"]
}
'
```

[Elasticsearch documentation for user creation](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/security-api-put-user.html)

Once this is done, you need to configure Mastodon to use the credentials for your newly created user.

In `.env.production`, adjust your configuration:

```bash
ES_USER=mastodon
ES_PASS=l0ng-r4nd0m-p@ssw0rd
```

You are all set, and your Elasticsearch server should be much more secure!

#### Reduced permissions in shared environments

If you are running in a shared environment with multiple consumers of the same ES server (Mastodon installs, other apps, etc), in addition to using `ES_PREFIX` as described above to isolate the generated search indexes, you can also provide more limited access to the role you create.

For example, changing `"names": ["*"]` to `"names": ["app_prefix_*"]` (where `app_prefix` matches the value you are using as an index prefix) will limit the access of the users with that role to operate only on the appropriate indices.

### Populate the indices

After saving the new configuration, restart Mastodon processes for it to take effect:

```bash
systemctl restart mastodon-sidekiq
systemctl reload mastodon-web
```

Now it's time to create the Elasticsearch indices and fill them with data:

```bash
su - mastodon
cd live
RAILS_ENV=production bin/tootctl search deploy
```

{{< hint style="info" >}}
Creating Elasticsearch indices could require more memory than the JVM (Java Virtual Machine) provides. If Elasticsearch crashes while creating indices, try to allocate more memory.

1. Create and open a file in the directory ```/etc/elasticsearch/jvm.options.d/``` (for example: ```nano /etc/elasticsearch/jvm.options.d/ram.options```)
2. Add following text and edit the allocated memory to your needs. As a rule of thumb, Elasticsearch should use about 25%-50% of your available memory. Do not allocate more memory than available.

    ```java-properties
    # Xms represents the initial size of total heap space
    # Xmx represents the maximum size of total heap space
    # Both values should be the same
    -Xms2048m
    -Xmx2048m
    ```

3. Save the file.
4. Restart Elasticsearch using ```systemctl restart elasticsearch```.
5. Retry creating Elasticsearch indices. If Elasticsearch still crashes, try to set a higher number.
{{< /hint >}}

## Search optimization for other languages

The default analyzer is tuned for English and other western languages, and may not perform as well with others. This configuration can be modified for any language that Elasticsearch supports. Reviewing the [chewy index docs] may be useful to prepare for these changes.

{{< hint style="warning" >}}
Adding language support will require code changes and should only be attempted if you are comfortable modifying Ruby code and installing ES extensions.
{{< /hint >}}

[chewy index docs]: https://github.com/toptal/chewy?tab=readme-ov-file#index-definition

### Chinese search optimization {#chinese-search-optimization}

Before creating indices in Elasticsearch, be sure to install the following extensions:

- [elasticsearch-analysis-ik](https://github.com/medcl/elasticsearch-analysis-ik)
- [elasticsearch-analysis-stconvert](https://github.com/medcl/elasticsearch-analysis-stconvert)

After those are installed, you need to modify the code definitions which generate the search indices. Within every index definition file (`app/chewy/*_index.rb`), make the following changes:

- Replace all `tokenizer: 'VALUE'` (whitespace, standard, keyword, etc) occurrences with `tokenizer: 'ik_max_word'`
- In every index that has an `analyzer: { content: ... }` definition, between the `filter` and `analyzer` sections, add:

  ```ruby
    char_filter: {
      tsconvert: {
        type: 'stconvert',
        keep_both: false,
        delimiter: '#',
        convert_type: 't2s',
      },
    },
  ```

- In those same files, in every `content: ...` section, add an option of `char_filter: %w(tsconvert)` to use that filter
