Connect and Configure Elasticsearch

Connect Zammad with Elasticsearch

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

  • Install from package

  • Install with Docker (the default stack already includes Elasticsearch)

Note

This guide uses the zammad run command prefix in command line examples. This prefix is only applicable to package installations. Check the console guide for more information.

Elasticsearch URL

Set the Elasticsearch server address; adapt it to your scenario.

Elasticsearch 7:

$ zammad run rails r "Setting.set('es_url', 'http://localhost:9200')"

Elasticsearch 8 and newer:

$ zammad run rails r "Setting.set('es_url', 'https://localhost:9200')"
Elasticsearch user and password (Elasticsearch 8 and newer)

Now you need your password which was shown during the installation.

Set Elasticsearch user:

$ zammad run rails r "Setting.set('es_user', 'elastic')"

Set Elasticsearch password. Replace <password> with the one you got during the installation of Elasticsearch. In case you need to create a new password, run /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic.

$ zammad run rails r "Setting.set('es_password', '<password>')"
Add certificate to Zammad (Elasticsearch 8 and newer)
Add it via Rails console:

In case you are installing a new Zammad and didn’t run through the getting started wizard already, add the certificate via console:

$ sudo cat /etc/elasticsearch/certs/http_ca.crt | zammad run rails r 'SSLCertificate.create!(certificate: STDIN.read)'
Add it via UI:

In case you already have a running and configured Zammad, you can add the certificate in Zammad’s admin settings (Settings > Security > SSL Certificates) as an alternative. To show and copy the auto-generated certificate from Elasticsearch, run:

$ sudo cat /etc/elasticsearch/certs/http_ca.crt

To add it in Zammad, either upload the certificate file or paste the content in the dialog. Make sure to copy/paste the delimiters (e.g. -----BEGIN CERTIFICATE-----) too.

In any case, you can find the certificate in the UI. This looks like this:

Screenshot shows certificate management in Zammad's admin settings
Build/rebuild the searchindex

Hint

  • The rebuild may take many hours or even days, if a lot of data is already present in a productive environment. However, you can safely run this during operating times without the risk of loosing data. As a downside, it could lead to reduced performance and that some data may not be shown in search results.

  • Consider specifying a number of CPU cores to be used for the rebuild (see example below).

Without specifying CPU cores:

$ zammad run rake zammad:searchindex:rebuild

Example with specifying 8 CPU cores:

$ zammad run rake zammad:searchindex:rebuild[8]

Optional settings

We collected some useful settings you may want to apply. For further information please have a look at Elastic’s documentation.

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')"