Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -1,141 +1,83 @@
# Deploying Meilisearch
# Meilisearch in HiveGrid deployen
This document covers production deployment of the Meilisearch service that
backs `packages/search` and the `search-indexer` worker job. Local
development uses the bundled docker-compose service — see
`docker-compose.yml` and `docs/features/search.md` for the application-side
contract.
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.
## Requirements
Lokale Entwicklung kann weiterhin den Service aus `docker-compose.yml`
verwenden. Der Anwendungs- und Tenant-Vertrag steht in
`docs/features/search.md`.
- Disk: 1–10 GiB per million indexed documents, SSD strongly recommended.
- Memory: 1 GiB minimum; allocate ~30 % of the dataset size for hot reads.
- Network: reachable only from `apps/web`, `apps/api` and the
`worker-general` service. **Never** expose port 7700 to the public
internet. The master key is the only auth boundary; if the port is open,
the index is open.
- TLS: terminate at the platform's ingress / load balancer; Meilisearch
itself does not speak TLS.
## Runtime-Vertrag
## Environment Variables
| 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. |
| Variable | Required | Purpose |
| --- | --- | --- |
| `MEILI_URL` | yes | URL the search wrapper and worker dial. Internal DNS only (e.g. `http://meilisearch.internal:7700`). |
| `MEILI_MASTER_KEY` | yes | Server-side secret. Min 32 bytes of entropy. Rotate via blue/green; never log. |
| `MEILI_ENV` | yes | `production` in production. Disables the unauthenticated dashboard. |
| `MEILI_NO_ANALYTICS` | recommended | Set to `true` to disable upstream telemetry. |
`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.
## Coolify (Hetzner) — recommended for the staging stack
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.
Coolify ships a "custom docker-compose" service type that maps 1:1 onto
the local layout. Paste the snippet below into the project's
docker-compose override (Coolify → Service → Configuration → Compose).
## Index-Namespace
```yaml
services:
meilisearch:
image: getmeili/meilisearch:v1.8
environment:
- MEILI_MASTER_KEY=${MEILI_MASTER_KEY}
- MEILI_ENV=production
- MEILI_NO_ANALYTICS=true
volumes:
- meilisearch-data:/meili_data
healthcheck:
test: ["CMD-SHELL", "wget -q -O - http://127.0.0.1:7700/health | grep -q 'available'"]
interval: 10s
timeout: 5s
retries: 6
start_period: 15s
restart: unless-stopped
networks:
- backend
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:
volumes:
meilisearch-data:
networks:
backend:
external: true
```text
logical: projects
physical: hivegrid-projects
```
Operator steps:
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.
1. Set `MEILI_MASTER_KEY` as a Coolify "secret" (Project → Variables →
"Encrypt"). Length ≥ 32 bytes; generate with `openssl rand -hex 32`.
2. Set `MEILI_URL=http://meilisearch:7700` on `apps/web`, `apps/api` and
the `worker-general` service so they resolve via the internal Docker
network. Do **not** map the port to the host.
3. Add a backup cron that snapshots the `meilisearch-data` volume:
## Staging-Rollout
```bash
# /etc/cron.daily/meilisearch-snapshot
docker exec meilisearch \
curl -X POST -H "Authorization: Bearer $MEILI_MASTER_KEY" \
http://127.0.0.1:7700/snapshots
```
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.
4. Verify `/health` is `available` after deploy; the worker logs
`meilisearch.connected` on cold start.
## Dedizierte VM — alternative (Hetzner Cloud)
For traffic spikes that outgrow the central Coolify host, run Meilisearch on
a dedicated Hetzner Cloud VM (e.g. CX22) with a 10 GB volume:
```bash
# Hetzner: attach a 10 GB volume and mount at /meili_data
ssh root@<instance> docker run -d --name meilisearch \
--restart unless-stopped \
-p 7700:7700 \
-v /meili_data:/meili_data \
-e MEILI_MASTER_KEY="$(cat /etc/meilisearch/master-key)" \
-e MEILI_ENV=production \
-e MEILI_NO_ANALYTICS=true \
getmeili/meilisearch:v1.8
```
Front the instance with a private network; never expose
port 7700 to the public internet. Apps reach it via the private DNS name
configured in the `MEILI_URL` env.
## Master-Key Rotation
1. Generate a new key: `openssl rand -hex 32`.
2. Set the new key as `MEILI_MASTER_KEY_NEW` in the secret store.
3. Bring up a parallel Meilisearch container with the new key; replicate
indexes via the snapshot/restore endpoint:
```bash
curl -X POST -H "Authorization: Bearer $OLD_KEY" \
"$OLD_MEILI/snapshots"
# copy the snapshot file, start new container pointing at it
```
4. Flip `MEILI_URL` on the apps to point at the new container.
5. Decommission the old container; rotate the secret-store key (move
`MEILI_MASTER_KEY_NEW` to `MEILI_MASTER_KEY`).
The wrapper's transparent SQL-LIKE fallback (`searchWithFallback`) keeps
search degraded-but-up during the cutover.
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
The Postgres database remains the source of truth. To rebuild Meilisearch
from scratch:
Postgres bleibt die Source of Truth. Ein Rebuild wird ausschließlich über
logische Namen und Outbox-Events gestartet:
```bash
pnpm cli search reindex --tenant=all --index=all
pnpm exec tsx packages/cli/bin/hivegrid-cli.mjs search reindex --tenant=all --index=all
```
This writes `search.index.<entity>.bulkreindex` outbox events only for the
currently supported bulk-reindex set. Today `--index=all` expands to KB
articles, CRM contacts, rows, and users. Entities are rejected until their
tenant-scoped projection has an explicit pager design. The `search-indexer` job
consumes the accepted events and pages over Postgres in 1000-row chunks.
Expected throughput: ~10 k documents per minute per worker replica.
## Backup Retention
Snapshots are full copies of the data directory. Retain at least 7 daily
snapshots offsite (S3 / Backblaze). The volume itself is also covered by
the platform's nightly volume backup if you keep that enabled.
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.