Reindex YourBOX Meilisearch

When To Use

Use this runbook when:

• The daily reconciliation reports a drift between PostgreSQL and the Meilisearch index.
• A Meilisearch upgrade requires reapplying the settings.
• A search ranking adjustment changes the index settings file.
• The Messenger consumer has been disabled for an extended outage and the projection lag exceeds 24 hours.

The runbook does not require a maintenance window. The search remains available throughout, with degraded freshness while the reindex runs.

Preconditions

• The PostgreSQL source is healthy.
• The Meilisearch instance is reachable through MEILISEARCH_URL.
• The Messenger consumer is running. If it is not, the runbook starts it first.

Procedure

1. Confirm the index is reachable.

   curl --silent --header "Authorization: Bearer ${MEILISEARCH_KEY}" \
     "${MEILISEARCH_URL}/health"

   Expected result: {"status":"available"}.

2. Drain the Messenger consumer.

   kubectl -n yourbox annotate deployment/yourbox-worker \
     yourbox.io/drain=true --overwrite
   kubectl -n yourbox rollout restart deployment/yourbox-worker

   Expected result: the consumer pod restarts in drain mode and processes already in flight messages without picking up new ones.

3. Reset the index.

   php app/bin/console catalog:search:reset --no-debug

   Expected result: the command reports Deleted index yourbox-videos. The search controller catches the missing index error and serves a degraded results page until the reindex completes.

4. Reapply the settings.

   php app/bin/console catalog:search:apply-settings \
     --settings=app/config/meilisearch/settings.json

   Expected result: the command reports Settings applied (task UID <N>). The task UID resolves under ${MEILISEARCH_URL}/tasks/<N>.

5. Run the reindex.

   php app/bin/console catalog:search:reindex --batch-size=500 \
     --no-debug

   Expected result: the command reports the document count copied per batch, with a final line Reindex succeeded: <N> documents. The number matches the published video count in PostgreSQL.

6. Resume the Messenger consumer.

   kubectl -n yourbox annotate deployment/yourbox-worker \
     yourbox.io/drain- --overwrite
   kubectl -n yourbox rollout restart deployment/yourbox-worker

   Expected result: the consumer restarts and processes the queued messages within the lag SLO.

7. Verify the search.

   curl --silent "${MEILISEARCH_URL}/indexes/yourbox-videos/search" \
     -H "Authorization: Bearer ${MEILISEARCH_KEY}" \
     -H "Content-Type: application/json" \
     --data '{"q":"one piece"}'

   Expected result: a JSON response with at least one hit matching the sample query (assuming the sample data is present in the environment).

Validation

• The Grafana panel YourBOX > Overview > Search latency p95 stays below 150 ms.
• The Prometheus metric yourbox_search_documents_total matches yourbox_videos_published_total.
• kubectl -n yourbox logs deployment/yourbox-worker --since=15m | grep -i meilisearch | grep -i error returns no results.

If This Does Not Work

If the reindex stalls, inspect the Meilisearch task queue:

curl --silent "${MEILISEARCH_URL}/tasks?statuses=processing,enqueued" \
  -H "Authorization: Bearer ${MEILISEARCH_KEY}"

If a task is stuck, cancel it and resume the reindex from the last batch identifier reported in the importer log:

curl --silent -X POST \
  "${MEILISEARCH_URL}/tasks/cancel?uids=<N>" \
  -H "Authorization: Bearer ${MEILISEARCH_KEY}"

Escalate to the platform on call when the Meilisearch instance reports disk pressure or memory pressure for more than 5 minutes.