Set up Elasticsearch

Zammad’s search function is powered by Elasticsearch, and requires one of:

Warning

Versions below 5.5 may continue to work for the time being, but are officially deprecated. Support will be dropped in upcoming releases.

Note

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

Direct Download:
 

Find the latest release on the downloads page, or see the installation guide for in-depth instructions. Then,

# Install the attachment plugin
$ sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment  # for 5.6+
$ sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install mapper-attachments # for 5.5

# Increase the virtual memory map limit
$ sudo sysctl -w vm.max_map_count=262144

and start Elasticsearch.

Note

🐋 Docker installations on macOS/Windows:

Setting the vm.max_map_count kernel parameter requires additional steps.

CentOS 7:
rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch
echo "[elasticsearch-7.x]
name=Elasticsearch repository for 7.x packages
baseurl=https://artifacts.elastic.co/packages/7.x/yum
gpgcheck=1
gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch
enabled=1
autorefresh=1
type=rpm-md"| sudo tee /etc/yum.repos.d/elasticsearch-7.x.repo
yum install -y java-1.8.0-openjdk elasticsearch
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
systemctl start elasticsearch
systemctl enable elasticsearch
Debian 8:
apt-get install apt-transport-https sudo wget
echo "deb http://ftp.debian.org/debian jessie-backports main" | sudo tee -a /etc/apt/sources.list.d/debian-backports.list
echo "deb https://artifacts.elastic.co/packages/7.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-7.x.list
wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
apt-get update
apt-get install -t jessie-backports openjdk-8-jre
apt-get install elasticsearch
sudo /var/lib/dpkg/info/ca-certificates-java.postinst configure
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
systemctl restart elasticsearch
systemctl enable elasticsearch
Debian 9:
apt-get install apt-transport-https sudo wget
echo "deb https://artifacts.elastic.co/packages/7.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-7.x.list
wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
apt-get update
apt-get install openjdk-8-jre-headless elasticsearch
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
systemctl restart elasticsearch
systemctl enable elasticsearch
Debian 10:
apt-get install apt-transport-https sudo wget
echo "deb https://artifacts.elastic.co/packages/7.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-7.x.list
wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
apt-get update
apt-get install openjdk-11-jre-headless elasticsearch
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
systemctl restart elasticsearch
systemctl enable elasticsearch
Ubuntu 16.04 & 18.04:
 
apt-get install apt-transport-https sudo wget
echo "deb https://artifacts.elastic.co/packages/7.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-7.x.list
wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
apt-get update
apt-get install openjdk-8-jre elasticsearch
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
systemctl restart elasticsearch
systemctl enable elasticsearch

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

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

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

Optional settings

Authentication:
# 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?

For HTTP Basic auth, try this nginx reverse proxy config.

Elasticsearch also supports authentication via its X-Pack paid subscription service Consult the official Elasticsearch guides for more details.

Index namespacing:
 
# Useful when connecting multiple services or Zammad instances
# to a single Elasticsearch server (to prevent name collisions during indexing).
$ zammad run rails r "Setting.set('es_index', Socket.gethostname.downcase + '_zammad')"
File-attachment indexing rules:
 
# Zammad supports searching by the contents of file attachments,
# which means Elasticsearch has to index those, too.
#
# Limiting such indexing can help conserve system resources.

# Files with these extensions will not be indexed
$ zammad run rails r "Setting.set('es_attachment_ignore', [ '.png', '.jpg', '.jpeg', '.mpeg', '.mpg', '.mov', '.bin', '.exe', '.box', '.mbox' ] )"

# Files larger than this size (in MB) will not be indexed
$ zammad run rails r "Setting.set('es_attachment_max_size_in_mb', 50)"