Set up Elasticsearch

Zammad’s search function is powered by Elasticsearch, and requires the ingest attachment plugin.

This guide uses the zammad run command prefix in command line examples. This prefix is only applicable to package installations (i.e., via apt/yum/zypper, or .deb/.rpm files).

If you installed from source, be sure to omit this prefix and run the bare rails ... or rake ... commands instead.

Step 1: Installation

Starting with Zammad 4.0, our packages allow you to decide whether to use elasticsearch or elasticsearch-oss.

elasticsearch-oss users please use below “direct download” tab for further installation steps.

Warning

Above does not apply to CentOS because of compatibility reasons.

$ apt install apt-transport-https sudo wget curl gnupg
$ echo "deb [signed-by=/etc/apt/trusted.gpg.d/elasticsearch.gpg] https://artifacts.elastic.co/packages/7.x/apt stable main"| \
  tee -a /etc/apt/sources.list.d/elastic-7.x.list > /dev/null
$ curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch | \
  gpg --dearmor | tee /etc/apt/trusted.gpg.d/elasticsearch.gpg> /dev/null
$ apt update
$ apt install elasticsearch
$ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment

After you installed Elasticsearch and its attachment plugin, ensure to enable it by default and start it.

$ systemctl start elasticsearch
$ systemctl enable elasticsearch

Note

🐋 Docker installations on macOS/Windows:

Setting the vm.max_map_count kernel parameter requires additional steps.

Step 2: Suggested Configuration

We use the following settings to optimize the performance of our Elasticsearch servers. Your mileage may vary.

# /etc/elasticsearch/elasticsearch.yml

# Tickets above this size (articles + attachments + metadata)
# may fail to be properly indexed (Default: 100mb).
#
# When Zammad sends tickets to Elasticsearch for indexing,
# it bundles together all the data on each individual ticket
# and issues a single HTTP request for it.
# Payloads exceeding this threshold will be truncated.
#
# Performance may suffer if it is set too high.
http.max_content_length: 400mb

# Allows the engine to generate larger (more complex) search queries.
# Elasticsearch will raise an error or deprecation notice if this value is too low,
# but setting it too high can overload system resources (Default: 1024).
#
# Available in version 6.6+ only.
indices.query.bool.max_clause_count: 2000

Note

For more information on the indices.query.bool.max_clause_count setting, see the Elasticsearch 6.6 release notes.

Step 3: Connect Zammad

Before proceeding here, make sure to install Zammad before running below commands, as this will fail otherwise.

# Set the Elasticsearch server address
$ zammad run rails r "Setting.set('es_url', 'http://localhost:9200')"

# Build the search index
$ zammad run rake zammad:searchindex:rebuild

# Optionally, you can specify a number of CPU cores which are used for
# rebuilding the searchindex, as in the following example with 8 cores:
$ zammad run rake zammad:searchindex:rebuild[8]

Starting with Elasticsearch 8+, you need to use a HTTPS URL in ‘es_url’ as ‘https://localhost:9200’ and configure an authentication (see HTTP Basic below).

Optional settings

# HTTP Basic
$ zammad run rails r "Setting.set('es_user', '<username>')"
$ zammad run rails r "Setting.set('es_password', '<password>')"

Hint

🤔 How do I set up authentication on my Elasticsearch server?

Elasticsearch provides many different authentication methods. Some of them may require paid X-Pack, please check the elastic documentation for more information.