View source for 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 <code>cURL</code> extension must be enabled.

=== Step 1: Install & Start Elasticsearch ===
Install Elasticsearch on your server (instructions below are for Ubuntu/Debian):

<syntaxhighlight lang="bash">
# 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
</syntaxhighlight>

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

=== Step 2: Download the MediaWiki Extensions ===
CirrusSearch depends on '''Extension:Elastica''' to serve as the PHP client bridge.

# Navigate to your MediaWiki <code>extensions/</code> directory:
<syntaxhighlight lang="bash">
cd /var/www/html/<yourWebDir>/extensions
</syntaxhighlight>

# Download both Elastica and CirrusSearch (replace <code>REL1_39</code> with your MediaWiki branch version, e.g., <code>REL1_40</code>, <code>REL1_43</code>):
<syntaxhighlight lang="bash">
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
</syntaxhighlight>

# '''Install PHP Dependencies:''' If you cloned the extensions via Git, you must install the Composer dependencies inside both extension folders:
<syntaxhighlight lang="bash">
cd Elastica && composer install --no-dev && cd ..
cd CirrusSearch && composer install --no-dev && cd ..
</syntaxhighlight>

=== Step 3: Configure LocalSettings.php ===
Open your <code>LocalSettings.php</code> file and add the following block at the bottom:

<syntaxhighlight lang="php">
// 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;
</syntaxhighlight>

=== Step 4: Generate and Bootstrap the Search Index ===
Run the maintenance scripts from your MediaWiki root directory to build and populate the Elasticsearch index.

# '''Configure the index structure:'''
<syntaxhighlight lang="bash">
php maintenance/run.php CirrusSearch:UpdateSearchIndexConfig
</syntaxhighlight>

# '''Re-enable live search updates:''' Go back into <code>LocalSettings.php</code> and '''remove or comment out''' the <code>$wgDisableSearchUpdate = true;</code> line.

# '''Populate the index with your wiki's page content:'''
<syntaxhighlight lang="bash">
php maintenance/run.php CirrusSearch:ForceSearchIndex --skipLinks --indexOnSkip
php maintenance/run.php CirrusSearch:ForceSearchIndex --skipParse
</syntaxhighlight>

*: ''Note: For smaller wikis, running just <code>php maintenance/run.php CirrusSearch:ForceSearchIndex</code> is usually sufficient.''

=== Step 5: Switch MediaWiki to Use CirrusSearch ===
Once indexing completes successfully, add the final setting to <code>LocalSettings.php</code> to hand search queries over to Elasticsearch:

<syntaxhighlight lang="php">
// Direct default search traffic to CirrusSearch
$wgSearchType = 'CirrusSearch';
</syntaxhighlight>

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

=== Step 6: LocalSettings.php Cleanup ===

<syntaxhighlight lang="php">
## 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;
</syntaxhighlight>

=== Step 7: Setup Crontab Job ===
====Job====
# Establish a job that runs every minute
# crontab -e
<syntaxhighlight lang="bash">
* * * * * /usr/bin/php /var/www/html/<yourWebDir>/maintenance/run.php runJobs --maxtime=60 >> /var/log/mediawiki/runJobs.log 2>&1
</syntaxhighlight>
====Logs====
# Setup a log dir (probably should revisit this some day and do a proper rotation)
<syntaxhighlight lang="bash">
sudo mkdir -p /var/log/mediawiki
sudo chown it:it /var/log/mediawiki
</syntaxhighlight>

== 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 <code>LocalSettings.php</code> 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:
<syntaxhighlight lang="php">
wfLoadExtension( 'Elastica' );
wfLoadExtension( 'CirrusSearch' );
$wgCirrusSearchServers = [ '127.0.0.1' ];
$wgSearchType = 'CirrusSearch';
</syntaxhighlight>

To this (commented out by adding <code>//</code>):
<syntaxhighlight lang="php">
// wfLoadExtension( 'Elastica' );
// wfLoadExtension( 'CirrusSearch' );
// $wgCirrusSearchServers = [ '127.0.0.1' ];
// $wgSearchType = 'CirrusSearch';
</syntaxhighlight>
*: ''Note: By removing <code>$wgSearchType</code>, 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:

<syntaxhighlight lang="bash">
php maintenance/run.php purgeCache
</syntaxhighlight>

=== 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:

<syntaxhighlight lang="bash">
sudo systemctl disable --now elasticsearch
</syntaxhighlight>
=== Step 5: Crontab ===
# Edit out or remove the schedule crontab job.

[[Category:Wiki]]
[[Category:Weblog-2026-08]]