HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/docs/deploy/meilisearch.md

Meilisearch in HiveGrid deployen

HiveGrid nutzt gemäß infra/STANDARDS.md §4 den zentralen Meilisearch im Estate. Staging und Production bekommen keinen eigenen Meilisearch-Service in Coolify. Der zentrale Dienst ist ausschließlich über das WireGuard-Mesh erreichbar und wird von der Estate-Infrastruktur betrieben und gesichert.

Lokale Entwicklung kann weiterhin den Service aus docker-compose.yml verwenden. Der Anwendungs- und Tenant-Vertrag steht in docs/features/search.md.

Runtime-Vertrag

Variable	Pflicht	Zweck
MEILI_URL	ja	Mesh-Adresse des zentralen Dienstes: http://10.42.0.4:7700.
MEILI_API_KEY	ja	Auf HiveGrid und hivegrid-*-Indizes beschränkter API-Key.

MEILI_MASTER_KEY gehört niemals in eine HiveGrid-App, einen HiveGrid-Worker oder eine HiveGrid-CI-Variable. Erstellung und Rotation des scoped API-Keys erfolgen mit dem Master-Key ausschließlich auf der Estate-Control-Ebene.

Die Runtime-Variablen müssen mindestens auf hivegrid-web, hivegrid-api und worker-general identisch gesetzt sein. Der Mesh-Endpunkt darf nicht über einen öffentlichen Port oder Proxy veröffentlicht werden.

Index-Namespace

Registry-Schemas, Outbox-Payloads, CLI-Parameter und Worker-Pager verwenden weiterhin logische Namen wie projects oder crm-contacts. Erst der Adapter in @hivegrid/search bildet diese zentral auf physische Meilisearch-UIDs ab:

logical:  projects
physical: hivegrid-projects

Aufrufer dürfen den Prefix nicht selbst ergänzen. SearchClient.index() verwirft bereits physisch präfixierte Namen, damit weder doppelte Prefixes noch ein zweiter, unpräfixierter Namespace entstehen. Der scoped API-Key muss ausschließlich Zugriffe auf hivegrid-* erlauben.

Staging-Rollout

1. Estate-Operator erstellt oder rotiert einen HiveGrid-scoped API-Key für hivegrid-*; der Master-Key bleibt außerhalb der Anwendung. Der Key braucht zusätzlich zu Index-, Dokument- und Settings-Rechten auch tasks.get, weil HiveGrid jede asynchrone Mutation bis zum terminalen Status bestätigt.
2. MEILI_URL und MEILI_API_KEY auf Web, API und worker-general setzen.
3. Für einen Namespace-Wechsel Web zunächst mit SEARCH_BACKEND=sql starten. Der Worker schreibt dabei weiter nach Meilisearch, aber kein bestehender Tenant liest aus einem unvollständig befüllten Index.
4. Alle drei Ressourcen mit demselben geprüften Image-SHA deployen. Der General-Worker legt alle registrierten hivegrid-*-Indizes an und bestätigt ihre Settings, bevor er den ersten Search-Job annimmt. Schlägt das fehl, beendet er den Start fail-closed.
5. /health beziehungsweise /readyz und die Worker-Logs prüfen, ohne Keys oder Verbindungs-URLs auszugeben.
6. Für jeden bestehenden Tenant alle unterstützten Registry-Indizes neu aufbauen. Nicht durch Bulk-Pager abgedeckte Indizes müssen über ihre jeweiligen Source-of-Truth-Projektionen vollständig replayed werden.
7. Dokumentanzahl und Tenant-Isolation je Index verifizieren. Erst wenn alle acht Indizes vollständig sind, SEARCH_BACKEND=meilisearch auf Web setzen und erneut deployen. Bis dahin bleibt SQL der explizite Read-Pfad.

Der Demo-Pro-Seed verifiziert seinen eigenen Tenant vollständig in allen acht Indizes. Das ersetzt keinen Backfill anderer Staging-Tenants und ist daher kein Signal, das globale Read-Gate vorzeitig umzuschalten.

Disaster Recovery

Postgres bleibt die Source of Truth. Ein Rebuild wird ausschließlich über logische Namen und Outbox-Events gestartet:

pnpm exec tsx packages/cli/bin/hivegrid-cli.mjs search reindex --tenant=all --index=all

Der search-indexer konsumiert die Events und schreibt über den zentralen Adapter in hivegrid-*. --index=all umfasst nur Indizes mit registriertem Bulk-Pager; nicht unterstützte Projektionen werden abgewiesen. Snapshot, Restore, Retention und Master-Key-Rotation des zentralen Dienstes gehören in die Runbooks des infra/-Repos und werden nicht in HiveGrid dupliziert.