Meilisearch operations for Scrypath adopters

This guide is for operators who run Scrypath against Meilisearch in development, staging, or production. It stays at the infrastructure and posture layer: where the engine runs, how to align versions with Scrypath’s expectations, and which companion guides carry the detailed recovery playbooks.

Guide map

• guides/sync-modes-and-visibility.md — canonical semantics for :inline, :oban, and :manual sync and what “accepted” work means for search visibility.
• guides/drift-recovery.md — symptom → diagnosis → action tables when the index and the database disagree.
• guides/common-mistakes.md — short wrong-model → fix notes when behaviour “feels” like data loss but is usually visibility or hydration drift.
• guides/operator-mix-tasks.md — thin mix scrypath.* entrypoints over the same Scrypath.* operator APIs referenced here.

Where Meilisearch runs

Treat Meilisearch as a separate stateful service beside your application and primary database:

• Development — local binary, Docker, or Compose; keep the HTTP URL stable in SCRYPATH_MEILISEARCH_URL (or your app’s equivalent runtime config) so Scrypath tasks and iex sessions agree on the same cluster.
• Production — run a supported Meilisearch release on infrastructure you operate (VM, Kubernetes, or managed offering that exposes the HTTP API Scrypath expects). Document the URL, master key handling, and TLS termination the same way you would for any other data store dependency.

Scrypath does not hide network or credential concerns: configure the backend URL and keys in the same runtime surfaces you use for Postgres and Oban.

Version alignment

Scrypath’s tests and examples track a pinned Meilisearch minor (see the Phoenix example README and CI service images for the current target). Before upgrading production:

• Confirm the new Meilisearch release notes for breaking HTTP or task semantics.
• Run your usual mix test plus any integration suites you enable with SCRYPATH_INTEGRATION=1 against a disposable cluster at the new version.

Staying within the supported matrix reduces “mystery” task failures that look like application bugs but are really engine behaviour changes.

Keys, TLS, and blast radius

• Scope API keys so production indexes are not writable from developer laptops unless you intend that explicitly.
• Prefer TLS between your app and Meilisearch wherever traffic crosses an untrusted network.
• Treat the master key like a database superuser password: rotation requires coordinated config updates on every Scrypath node and worker.

Backups vs rebuilding from Postgres

Meilisearch is a search projection of data you already store in the primary database (or import pipeline). For most teams:

• Rebuilding — acceptable and often simplest after large schema or settings changes: run a managed Scrypath.reindex/2 or Scrypath.backfill/2 path once Meilisearch is healthy, using the same semantics described in guides/sync-modes-and-visibility.md.
• Backups — still valuable for large corpora or when rebuild time is unacceptable; snapshot Meilisearch data directories or vendor backups on the schedule your RPO/RTO demands, and keep Postgres (or source-of-truth) backups authoritative.

If you are unsure which path applies, start with drift triage in guides/drift-recovery.md before choosing destructive rebuild steps.

Health checks operators actually use

At minimum, operators should be able to answer:

• Can the app reach GET /health (or your platform’s equivalent) on the configured Meilisearch base URL with the configured key?
• Do Meilisearch tasks for your indexes show sustained failed states while Postgres writes succeed?
• Does Scrypath.sync_status/2 report backlog or backend errors consistent with what Meilisearch’s task list shows?

Use mix scrypath.status for a compact terminal snapshot when MIX_ENV and runtime flags match production (--backend, --sync-mode, --index-prefix, --meilisearch-url as documented in guides/operator-mix-tasks.md).

Footguns

• Assuming “sync returned :ok” means the user’s next search is fresh — see guides/sync-modes-and-visibility.md; accepted work is not the same thing as search visibility.
• Treating Meilisearch as the source of truth for business data — it is a search index; reconcile or rebuild from your primary store when in doubt.
• Running CI or examples against a different Meilisearch major/minor than production — keep local Compose files and CI images aligned with what you ship, then document intentional drift if any.

For structured recovery steps once a concrete symptom is identified, continue in guides/drift-recovery.md.