Unlocking Advanced Search Capabilities with CirrusSearch in MediaWiki

The CirrusSearch extension replaces MediaWiki's default search with an Elasticsearch (or, since MediaWiki 1.44, OpenSearch 1.3) backend — the engine behind Wikipedia's search. This article is the operations side: requirements, installation, indexing and day-to-day maintenance. The query language itself is covered in the companion guide on this blog.

Requirements

• Elasticsearch — MediaWiki 1.39+ requires ES 7.10.2 (older 6.8 only via a compatibility layer); MediaWiki 1.44+ also accepts OpenSearch 1.3. ES needs a Java runtime; the official Docker image is the fastest path
• The Elastica extension — required PHP library dependency; installed and loaded before CirrusSearch
• PHP with cURL — CirrusSearch talks HTTP to the search cluster
• RAM — budget at least 1–2 GB for a small wiki's cluster (JVM heap); a shared host's 256 MB VPS will not run it

Installation

cd extensions
composer require mediawiki/cirrussearch

(or clone both extension repos from Gerrit and run composer install --no-dev in each). Then in LocalSettings.php:

wfLoadExtension( 'Elastica' );
wfLoadExtension( 'CirrusSearch' );
// or via 'cirrussearch' composer package:

$wgCirrusSearchServers = [ 'http://127.0.0.1:9200' ];

Create the index — the real setup — with the extension's maintenance scripts (they live in extensions/CirrusSearch/maintenance/):

php extensions/CirrusSearch/maintenance/UpdateSearchIndexConfig.php --startOver
php extensions/CirrusSearch/maintenance/ForceSearchIndex.php

The first ForceSearchIndex run parses and indexes every page; on large wikis this takes hours and should run with the job queue. Verify on Special:Version and with a test search.

How indexing updates work

Page edits enqueue index jobs:

• Full-text updates flow through the job queue and appear within minutes (up to ~30 min is normal)
• Template changes update every transcluding page — on template-heavy wikis this is the largest job source; the docs recommend running the queue with Redis
• The autocomplete 'completion suggester' refreshes roughly daily, separately from full-text

Upgrade and maintenance notes

• Search backend version — every ES upgrade risks compatibility drift; the extension page pins the required version per MediaWiki release, and before a MediaWiki upgrade check whether your ES version is still supported (the 1.42-wmf era moved to OpenSearch — plan accordingly if you follow Wikimedia's path)
• Reindex triggers — after UpdateSearchIndexConfig schema changes, a full or page-batch reindex via ForceSearchIndex.php --buildChunks is the standard procedure
• Index base name — if the wiki's MySQL database name contains uppercase letters, indexing fails; set $wgCirrusSearchIndexBaseName to a lowercase name
• Blacklist nothing, monitor — watch the cluster health (_cluster/health), job queue depth, and Special:Search error logs; most production issues are memory or network, not MediaWiki-side

Do you actually need it?

CirrusSearch is the biggest search-quality jump available, but it is also the heaviest extension around: an extra JVM-based service, indexing jobs and ongoing ES maintenance. The default search covers small wikis fine; install CirrusSearch when pages number in the low thousands, when full-text quality matters (documentation portals), or when search needs to index template-expanded content. The extension page's hardware guidance and the help page (for users) round out the decision.