Search

Overview

CirrusSearch replaces MediaWiki's built-in database search with Elasticsearch: better relevance, "did you mean" suggestions, and fast full-text search that scales with your content. Canasta bundles the CirrusSearch and Elastica extensions and ships an Elasticsearch service in every instance, disabled by default.

Enabling search is three steps: start Elasticsearch, enable and configure CirrusSearch, and build the initial index. From then on, the job queue keeps the index current as pages change — no ongoing maintenance is needed.

Everything on this page works the same on Docker Compose and Kubernetes.

Requirements

• Memory. Elasticsearch is Java-based and memory-intensive — expect it to use 1–2 GB. If you also run the observability stack (OpenSearch + Logstash), the combined footprint is significant. See System requirements.
• Kubernetes: Canasta CLI 4.9.1 or later. Earlier versions cannot pull the stock Elasticsearch image on Kubernetes, never run the indexing jobs, and cannot run the indexing commands from a remote controller.
• Canasta pins Elasticsearch 7.10.2 on both orchestrators — the release line CirrusSearch supports. To run a different image (for example, one with extra analysis plugins), see Custom Elasticsearch plugins.

Step 1 — Start Elasticsearch

For an existing instance:

canasta config set CANASTA_ENABLE_ELASTICSEARCH=true

For a new instance, put the setting in an env file and pass it to canasta create:

CANASTA_ENABLE_ELASTICSEARCH=true

canasta create -i myinstance -w mywiki -e custom.env

On Docker Compose this starts the elasticsearch container (the CLI syncs the elasticsearch profile in COMPOSE_PROFILES). On Kubernetes the CLI enables Elasticsearch in the instance's Helm values and rolls out an elasticsearch pod. The first start pulls the Elasticsearch image and the service can take a minute or two to become ready — on Kubernetes, wait for the elasticsearch pod to report 1/1 Running before building the index.

Step 2 — Enable and configure CirrusSearch

Enable the two extensions:

canasta extension enable CirrusSearch,Elastica

Then point CirrusSearch at the Elasticsearch service and make it the wiki's search engine. Create config/settings/global/Search.php in the instance directory:

<?php
$wgCirrusSearchServers = [ 'elasticsearch' ];
$wgSearchType = 'CirrusSearch';

The hostname elasticsearch resolves to the bundled service on both orchestrators. Both settings are required: without $wgCirrusSearchServers, CirrusSearch looks for Elasticsearch on localhost and finds nothing; without $wgSearchType, MediaWiki keeps using its database search.

On Docker Compose the new settings file takes effect on the next page load. On Kubernetes, sync it to the cluster first:

canasta reconcile

Step 3 — Build the search index

This is a three-step process, run in order:

1. Configure index mappings:

canasta maintenance extension CirrusSearch:UpdateSearchIndexConfig --reindexAndRemoveOk --indexIdentifier now

2. Index page content:

canasta maintenance extension CirrusSearch:ForceSearchIndex --skipLinks --indexOnSkip

3. Index links:

canasta maintenance extension CirrusSearch:ForceSearchIndex --skipParse

On large wikis, steps 2 and 3 can take a significant amount of time. See Running extension maintenance scripts for general usage of the extension maintenance command.

Verifying

Search for a phrase you know appears on a page — via the search box, Special:Search, or the API:

curl 'https://<your-domain>/w/api.php?action=query&list=search&srsearch=<term>&format=json'

Then edit a page, wait a few seconds, and search for the new text: the job queue indexes every edit automatically, so new content should appear without any manual reindexing. If it does not, see Troubleshooting.

Wiki farms

In a wiki farm, each wiki has its own search index. Without -w, the index-building commands run on all wikis; use -w to target one:

canasta maintenance extension -w docs CirrusSearch:UpdateSearchIndexConfig --reindexAndRemoveOk --indexIdentifier now
canasta maintenance extension -w docs CirrusSearch:ForceSearchIndex --skipLinks --indexOnSkip
canasta maintenance extension -w docs CirrusSearch:ForceSearchIndex --skipParse

Importing a database

Import a database before configuring CirrusSearch and before starting Elasticsearch. A database dump includes MediaWiki's job table, so importing restores the source wiki's pending job queue and the job runner begins draining it immediately. If CirrusSearch is loaded and Elasticsearch is reachable at that moment, those jobs write documents to an index that UpdateSearchIndexConfig has not created yet. Elasticsearch creates it implicitly as an ordinary index rather than the alias CirrusSearch expects, and the index build later fails with Primary index was expected to be an alias.

When setting a wiki up from an existing database — restoring a backup, or migrating an existing wiki onto Canasta — use this order:

1. Create the instance and import the database, with Elasticsearch off and no CirrusSearch configuration in place.
2. Enable Elasticsearch (step 1) and configure CirrusSearch (step 2).
3. Restart the instance.
4. Run canasta maintenance update, so that the tables belonging to the wiki's extensions are created.
5. Build the index (step 3).

Importing into a wiki whose index has already been built needs no special handling: the aliases exist, so the restored jobs index into them normally. Only a first import into a wiki where CirrusSearch was configured before the index was built is affected.

If this has already happened, delete the wiki's content indices and build the index again. Leave the mw_cirrus_metastore index alone — it is created correctly. To see what exists:

canasta maintenance exec -s elasticsearch -- curl -s 'localhost:9200/_cat/indices?v'

Then remove the wiki's own indices, named after the wiki ID:

canasta maintenance exec -s elasticsearch -- curl -s -XDELETE 'localhost:9200/mywiki_content,mywiki_general'

Then run the three commands in step 3 in order.

Recreating the index

To destroy and recreate the index (for example, after changing analyzers or mappings), use --startOver in step 1, then run steps 2 and 3 as usual:

canasta maintenance extension CirrusSearch:UpdateSearchIndexConfig --startOver

Custom Elasticsearch plugins

To run Elasticsearch with extra plugins (for example, analysis-icu for ICU-based collation), build a custom image and point CANASTA_ELASTICSEARCH_IMAGE at it. See Custom Elasticsearch plugins for the per-orchestrator recipes.

Disabling search

Remove (or comment out) the $wgSearchType line in config/settings/global/Search.php so MediaWiki returns to its database search, then stop the Elasticsearch service:

canasta config set CANASTA_ENABLE_ELASTICSEARCH=false

Stopping Elasticsearch while $wgSearchType still names CirrusSearch breaks search entirely rather than falling back.

Troubleshooting

• index(es) do not exist. Did you forget to run updateSearchIndexConfig? — step 3's indexing commands were run before step 1's UpdateSearchIndexConfig, or the index build never happened. Run the three commands in order.
• Primary index was expected to be an alias — the wiki's index exists as an ordinary Elasticsearch index instead of an alias. Either an earlier UpdateSearchIndexConfig was interrupted partway, or a database was imported while CirrusSearch was already configured and Elasticsearch was running, letting the restored job queue create the index implicitly — see Importing a database. Run UpdateSearchIndexConfig again with --startOver; if the error persists, delete the wiki's indices in Elasticsearch and rerun.
• New edits never show up in search results (but the initial index works) — the indexing happens in the job queue, so check it: canasta maintenance script showJobs --group. On Kubernetes, CLI versions before 4.9.1 had a jobrunner defect that silently failed every indexing job — upgrade and the queue drains on its own.
• Elasticsearch container never becomes ready — give it a couple of minutes on modest hardware, and check its memory: the container is limited and Elasticsearch may be OOM-killed on hosts with little free RAM.