Switching Koha from Zebra to Elasticsearch

Once Elasticsearch itself is running, the Koha side is four steps: put the server address in koha-conf.xml, set the SearchEngine system preference to Elasticsearch, build the indexes with koha-elasticsearch --rebuild, and start koha-es-indexer so they stay current. Zebra keeps working the whole time, which is what makes this reversible.

Koha talks to Elasticsearch through a Perl client, and each Koha release supports a particular range of server versions. That range moves, so check your own release's notes and the community wiki before installing a server rather than taking a version number from any guide, including this one. An unsupported major version does not fail politely — it connects, indexes, and returns wrong or empty results.

Install the server on its own host if you can. It is a separate service with its own memory appetite and its own upgrade cycle, and putting it beside the database on a small machine is the usual reason a switch to Elasticsearch makes a catalog slower rather than faster.

Every instance already has an <elasticsearch> block in its configuration, filled in when the instance was created:

 <elasticsearch>     <server>localhost:9200</server>     <index_name>koha_library</index_name>     <cxn_pool>Static</cxn_pool> </elasticsearch>

Two things to get right. <server> may be repeated, once per node in a cluster. <index_name> must be unique across everything sharing that Elasticsearch — Koha appends _biblios and _authorities to it, so two instances with the same name silently share one index and each sees the other's records. On a server with several libraries this is the mistake to check twice.

For an instance that does not exist yet, koha-create takes --elasticsearch-server and writes the block for you.

1. 1In the staff interface, go to Administration → Global system preferences and search for SearchEngine.
2. 2Change it from Zebra to Elasticsearch and save.

This is the switch itself, and it is instant — which is why the index has to be built next, not first. Searching before the build finishes returns whatever is in the index so far, which is usually nothing.

$ sudo koha-elasticsearch --rebuild -d -v library Indexing biblios218430 records indexedIndexing authorities41207 records indexed

-d deletes the existing index before rebuilding, which is what you want on a first run and after any mapping change. -v makes it report progress. On a large catalog -p runs several processes in parallel — useful, and worth introducing carefully rather than starting at the maximum your CPU count allows.

To rebuild only one side of it later, -b is biblios and -a is authorities.

This is the step people miss, and the symptom is delayed and confusing: searching works perfectly on the day of the switch, and weeks later new records cannot be found. Nothing keeps the index current unless the indexer is running.

$ sudo koha-es-indexer --start library$ sudo koha-es-indexer --status library ES indexer running for library

Then confirm it survives a reboot, because a service started by hand does not: reboot a test server, or at minimum re-check the status after systemctl restart koha-common.

1. 1Search the OPAC for a title you know is in the catalog. It should be found.
2. 2Edit a record's title slightly, save, wait a few seconds, and search for the new wording. If the old wording still matches and the new one does not, the indexer is not running.
3. 3Search for something with a diacritic, and something in a non-Latin script if your catalog has one. Analyzer problems show up here rather than on English titles.

Set SearchEngine back to Zebra. Nothing else has to be undone — Zebra's index was never switched off, and the records themselves are in the database, untouched by any of this. If Zebra's index has gone stale in the meantime, rebuild it and you are exactly where you started.

That is the honest reason to try it on a copy first: the switch back is cheap, and the migration of expectations is not.

Elasticsearch is not simply a faster Zebra. It changes relevance ranking, facets, and how much control you have over which MARC fields are searchable and how they are weighted — that mapping is editable in the staff interface, which is the real reason larger libraries move. It is also a second daemon to run, monitor, patch and back up.

Whether that trade is right for a given library is a decision rather than a procedure — Zebra or Elasticsearch argues it with the costs stated. This page is only what to do once the decision is made.

One consequence worth knowing before you commit: with Elasticsearch, a search failure is now a possible outage. If the Elasticsearch host is unreachable, searching stops, even though Koha and the database are perfectly healthy. Monitor it like a component of the catalog, because after this change that is what it is.