ElasticSearch on MediaWiki

Installing and Configuring CirrusSearch with Elasticsearch

Setting up CirrusSearch with Elasticsearch requires three main phases: installing the Elasticsearch cluster, downloading the required MediaWiki extensions (Elastica and CirrusSearch), and building the search index via MediaWiki maintenance scripts.

Prerequisites

• MediaWiki 1.39+: Recommended Elasticsearch 7.10.2 (or OpenSearch 1.3+).
• PHP: The PHP cURL extension must be enabled.
• Composer: See https://getcomposer.org/install for more information.

Composer Install

sudo apt update
sudo apt upgrade
sudo apt install curl php-cli php-mbstring git unzip
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php --install-dir=/usr/local/bin --filename=composer

Step 1: Install & Start Elasticsearch

Install Elasticsearch on your server (instructions below are for Ubuntu/Debian):

# Install Java runtime if not already installed
sudo apt update && sudo apt install -y openjdk-17-jre-headless

# Install Elasticsearch 7.x
wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-7.10.2-amd64.deb
sudo dpkg -i elasticsearch-7.10.2-amd64.deb

# Enable and start the service
sudo systemctl enable --now elasticsearch

To verify it is running on localhost:9200, test it in your terminal with curl http://localhost:9200.

Step 2: Download the MediaWiki Extensions

CirrusSearch depends on Extension:Elastica to serve as the PHP client bridge.

1. Navigate to your MediaWiki extensions/ directory:

cd /var/www/html/<yourWebDir>/extensions

1. Download both Elastica and CirrusSearch (replace REL1_39 with your MediaWiki branch version, e.g., REL1_40, REL1_43):

git clone -b REL1_43 https://gerrit.wikimedia.org/r/mediawiki/extensions/Elastica
git clone -b REL1_43 https://gerrit.wikimedia.org/r/mediawiki/extensions/CirrusSearch

1. Install PHP Dependencies: If you cloned the extensions via Git, you must install the Composer dependencies inside both extension folders:

cd Elastica && composer config policy.advisories.block false && composer install --no-dev && cd ..
cd CirrusSearch && composer config policy.advisories.block false && composer install --no-dev && cd ..

Step 3: Configure LocalSettings.php

Open your LocalSettings.php file and add the following block at the bottom:

// 1. Load the required extensions
wfLoadExtension( 'Elastica' );
wfLoadExtension( 'CirrusSearch' );

// 2. Specify your Elasticsearch server location
$wgCirrusSearchServers = [ '127.0.0.1' ];

// 3. Temporarily disable search updates during bootstrapping
$wgDisableSearchUpdate = true;

Step 4: Generate and Bootstrap the Search Index

Run the maintenance scripts from your MediaWiki root directory to build and populate the Elasticsearch index.

1. Configure the index structure:

php maintenance/run.php CirrusSearch:UpdateSearchIndexConfig

1. Re-enable live search updates: Go back into LocalSettings.php and remove or comment out the $wgDisableSearchUpdate = true; line.

1. Populate the index with your wiki's page content:

php maintenance/run.php CirrusSearch:ForceSearchIndex --skipLinks --indexOnSkip
php maintenance/run.php CirrusSearch:ForceSearchIndex --skipParse

• Note: For smaller wikis, running just php maintenance/run.php CirrusSearch:ForceSearchIndex is usually sufficient.

Step 5: Switch MediaWiki to Use CirrusSearch

Once indexing completes successfully, add the final setting to LocalSettings.php to hand search queries over to Elasticsearch:

// Direct default search traffic to CirrusSearch
$wgSearchType = 'CirrusSearch';

Test a search query on your wiki's Special:Search page. Your results should now be powered by Elasticsearch!

Step 6: LocalSettings.php Cleanup

## CUSTOM ELASTIC SEARCH
// Force CirrusSearch overrides at the very end of LocalSettings.php
wfLoadExtension( 'Elastica' );
wfLoadExtension( 'CirrusSearch' );

$wgSearchType = 'CirrusSearch';
$wgCirrusSearchServers = [ '127.0.0.1' ];

// Force exact database prefix matching for CirrusSearch
$wgCirrusSearchClusterOverrides = [
    'default' => [
        'replica' => '127.0.0.1'
    ]
];

// Ensure fallback to core MySQL is explicitly disabled for testing
$wgSearchType = 'CirrusSearch';
$wgCirrusSearchEnableDynamicHighlighter = false;

$wgJobRunRate = 0;

Step 7: Setup Crontab Job

Job

1. Establish a job that runs every minute
2. crontab -e

* * * * * /usr/bin/php /var/www/html/<yourWebDir>/maintenance/run.php runJobs --maxtime=60 >> /var/log/mediawiki/runJobs.log 2>&1

Logs

1. Setup a log dir (probably should revisit this some day and do a proper rotation)

sudo mkdir -p /var/log/mediawiki
sudo chown it:it /var/log/mediawiki

Reverting to the Default MediaWiki Search

If you are experiencing issues with CirrusSearch or simply want to revert to MediaWiki's native MySQL/MariaDB database search, follow these steps to safely disable the extension.

Step 1: Edit LocalSettings.php

Open your LocalSettings.php file and locate the configuration block for CirrusSearch.

You must remove or comment out the line that sets the search engine type, as well as the extension loading commands.

Change this:

wfLoadExtension( 'Elastica' );
wfLoadExtension( 'CirrusSearch' );
$wgCirrusSearchServers = [ '127.0.0.1' ];
$wgSearchType = 'CirrusSearch';

To this (commented out by adding //):

// wfLoadExtension( 'Elastica' );
// wfLoadExtension( 'CirrusSearch' );
// $wgCirrusSearchServers = [ '127.0.0.1' ];
// $wgSearchType = 'CirrusSearch';

• Note: By removing $wgSearchType, MediaWiki automatically falls back to its default internal search engine.

Step 2: Clear the MediaWiki Cache

MediaWiki caches configuration settings. To ensure the wiki immediately recognizes that CirrusSearch has been disabled, purge the application cache from your terminal in the MediaWiki root directory:

php maintenance/run.php purgeCache

Step 3: Verify the Changes

Go to your wiki in a web browser and try using the search bar. The results should now load using the standard MediaWiki search interface.

Step 4: (Optional) Stop the Elasticsearch Service

Elasticsearch consumes a significant amount of RAM (often 1GB+). If you do not plan to use it again or are permanently abandoning CirrusSearch, you should stop and disable the background service to free up your server resources:

sudo systemctl disable --now elasticsearch

Step 5: Crontab

1. Edit out or remove the schedule crontab job.