Set up Elasticsearch¶
Zammad’s search function is powered by Elasticsearch, and requires the ingest attachment plugin.
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¶
Note
🧐 To use OSS or not to use…
Starting with Zammad 4.0 our packages allow you to decide whether to use
elasticsearch
orelasticsearch-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
$ 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
$ 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"| tee /etc/yum.repos.d/elasticsearch-7.x.repo
$ yum install -y elasticsearch
$ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
$ 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"| tee /etc/zypp/repos.d/elasticsearch-7.x.repo
$ zypper install elasticsearch
$ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
Find the latest release on the downloads page, or see the installation guide for in-depth instructions. Ensure to also install the fitting (and mandatory!) attachment plugin for elasticsearch.
If you prefer the Open Source version of Elasticsearch, please use the Elasticsearch-OSS download page.
# Install the attachment plugin
$ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
# Increase the virtual memory map limit
$ sysctl -w vm.max_map_count=262144
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¶
Hint
🤓 Before proceeding here…
Make sure to install Zammad before running below commands, as this will fail other wise.
# 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
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.
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')"
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)"