README

Search replaces the native Flarum search functionality which relies on MySQL badly performing fulltext search with one that is completely relying on the proven elasticsearch engine.

Features

• Sync discussions and posts to Elasticsearch using your queue, unobtrusively for the user.
• Reduces search loading times to well below 400ms (local tests with 50,000 discussions: 260ms)
• Uses Flarum's group permissions and tags system.
• Compatible with Friends of Flarum Byōbu.

Requirements

• Elasticsearch 7.x or OpenSearch 1.x+
• A non-sync queue driver with a running worker (php flarum queue:work) is strongly recommended for production. The extension works with the default sync driver, but index jobs run inline which adds latency to user-facing changes like posting.

Installation

composer require blomstra/search:*

Enable the extension in the admin area and configure the Elasticsearch endpoint and index name in the extension settings.

Setting up the index

First install

Run the build command once. It creates a timestamped concrete index, immediately aliases your configured index name to it, and begins queuing documents. Search is available and improves as the queue processes:

php flarum blomstra:search:index build
php flarum queue:work

Subsequent rebuilds (zero-downtime)

When you need to rebuild the full index (e.g. after a mapping change):

# Simple rebuild — promotes automatically once all jobs are queued
php flarum blomstra:search:index build

# Or keep a backup of the old index in case you need to roll back
php flarum blomstra:search:index build --keep-backup

After the queue drains, fill any gaps from content posted during the build:

php flarum blomstra:search:index fill

If you kept a backup and want to roll back:

php flarum blomstra:search:index rollback

Once satisfied with the new index, drop the backup:

php flarum blomstra:search:index discard --backup

Blue-green rebuild (manual promotion)

Use --staging to keep the old index live until you explicitly promote:

# 1. Build into a staging index — live index is untouched
php flarum blomstra:search:index build --staging

# 2. Drain the queue
php flarum queue:work --stop-when-empty

# 3. Promote the staging index to live
php flarum blomstra:search:index promote
# Or keep the old index as a backup:
php flarum blomstra:search:index promote --keep-backup

Resuming or cancelling an interrupted build

If a build is interrupted, re-run it with the appropriate flag:

# Resume each seeder from where it left off
php flarum blomstra:search:index build --resume

# Drop the staging index and start completely fresh
php flarum blomstra:search:index build --fresh

# Cancel the build without starting a new one
php flarum blomstra:search:index discard --pending

Filling gaps in an existing index

If documents are missing from the live index (e.g. due to queue failures):

php flarum blomstra:search:index fill

Updating the mapping only

To push a mapping change to the live index without rebuilding:

php flarum blomstra:search:index mapping

Command reference

FAQ

Queue configuration

"Can I dispatch indexing jobs to a specific queue?"

Yes:

\Blomstra\Search\Jobs\Job::$onQueue = 'search';

"I have a different question"

Reach out ot us via https://support.on-floxum.com/t/ext-search . If you have an active subscription, please mention what plan you are on.

• Floxum provides managed Flarum hosting.
• https://floxum.com
• https://support.on-floxum.com/t/ext-search

Icon made by Freepik from Flaticon.