Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
@@ -0,0 +1,195 @@
|
||||
# Normale Rhein-Main-Staging-Daten für `demo-pro-crm`
|
||||
|
||||
Der Seed baut den Staging-Tenant als synthetischen SHK-Betrieb mit 50 Mitarbeitern
|
||||
(17 im Büro, 33 im Baustellen-/Kundendienst), 783 Kontakten, 537 Projekten und den
|
||||
dazugehörigen operativen Datensätzen auf. Die 33 Feldmitarbeiter arbeiten in 15
|
||||
Zweier-Kolonnen und einer Dreier-Kolonne. Das Büro besteht aus Geschäftsführung
|
||||
(1), Vertriebsleitung (1), Vertrieb (3), Backoffice (4), Marketing (1) und
|
||||
Projekt-/Bauleitung (7). Der Seed ist bewusst **nicht** an `SEED_ON_BOOT` gekoppelt.
|
||||
|
||||
Die fachlichen Datensätze werden dabei wie normale Betriebsdaten gespeichert
|
||||
(`isDemoData=false`). Der technische Slug bindet den Reset an den richtigen Tenant;
|
||||
deterministische IDs und interne Import-Metadaten halten die Herkunft nachvollziehbar.
|
||||
Kontakte, Projekte, Aufgaben und Dateien müssen deshalb ohne `demo=show` oder einen
|
||||
Demo-Schalter sichtbar sein.
|
||||
|
||||
Der Staging-Deploy setzt auf dem Web-Resource zusätzlich
|
||||
`SEED_DEMO_PRO_MANAGED=true`. Dadurch überspringt der bestehende Boot-Demo-Seed
|
||||
`demo-pro-crm` vollständig: Er verändert dort weder Mitgliedschaften noch Plan,
|
||||
ProductCore, Buchungen, Projekte oder Automationen. Starter und Business bleiben im
|
||||
bisherigen Boot-Seed. Das Flag darf nicht auf Production gesetzt werden und muss auf
|
||||
Staging aktiv bleiben, damit spätere Deploys den hier verifizierten Pro-Datensatz nicht
|
||||
wieder mit Legacy-Fixtures vermischen.
|
||||
|
||||
## Bedienung
|
||||
|
||||
```bash
|
||||
pnpm seed:demo-pro --dry-run
|
||||
|
||||
SENTRY_ENVIRONMENT=staging \
|
||||
SEED_DEMO_PRO_ALLOWED=true \
|
||||
SEED_DEMO_PRO_EXPECTED_TENANT_ID='<exakte-staging-tenant-id>' \
|
||||
SEED_DEMO_PRO_EXPECTED_DATABASE='<exakter-staging-datenbankname>' \
|
||||
SEED_DEMO_PRO_EXPECTED_DATABASE_HOST='<exakter-host:port>' \
|
||||
SEED_DEMO_PRO_EXPECTED_STORAGE_BUCKET='hivegrid-staging-media' \
|
||||
SEED_DEMO_PRO_EXPECTED_STORAGE_ENDPOINT='<exakter-staging-s3-endpoint>' \
|
||||
SEED_DEMO_PRO_WORKERS_DRAINED=true \
|
||||
SEED_DEMO_PRO_OUTBOUND_SANDBOX=true \
|
||||
SEED_DEMO_USER_PASSWORD='<starkes-zufaelliges-secret-aus-dem-secret-store>' \
|
||||
pnpm seed:staging-data --apply --confirm=demo-pro-crm
|
||||
|
||||
SENTRY_ENVIRONMENT=staging pnpm seed:demo-pro --verify
|
||||
|
||||
SENTRY_ENVIRONMENT=staging \
|
||||
SEED_DEMO_PRO_ALLOWED=true \
|
||||
SEED_DEMO_PRO_EXPECTED_TENANT_ID='<exakte-staging-tenant-id>' \
|
||||
SEED_DEMO_PRO_EXPECTED_DATABASE='<exakter-staging-datenbankname>' \
|
||||
SEED_DEMO_PRO_EXPECTED_DATABASE_HOST='<exakter-host:port>' \
|
||||
SEED_DEMO_PRO_EXPECTED_STORAGE_BUCKET='hivegrid-staging-media' \
|
||||
SEED_DEMO_PRO_EXPECTED_STORAGE_ENDPOINT='<exakter-staging-s3-endpoint>' \
|
||||
SEED_DEMO_PRO_WORKERS_DRAINED=true \
|
||||
SEED_DEMO_PRO_OUTBOUND_SANDBOX=true \
|
||||
pnpm seed:staging-data --cleanup --confirm=demo-pro-crm
|
||||
```
|
||||
|
||||
`apply` und `cleanup` verweigern jeden anderen Tenant sowie jede Umgebung außer
|
||||
Staging. Zusätzlich müssen Tenant-ID, Datenbankname, Datenbank-Host mit Port,
|
||||
S3-Provider, Bucket und Endpoint mit den im Staging-Secret-Store hinterlegten
|
||||
Bindings exakt übereinstimmen. Lokaler Storage und fremde S3-Buckets werden vor
|
||||
der ersten Mutation abgelehnt. Der
|
||||
Apply-Lauf wartet standardmäßig bis zu 300 Sekunden auf die
|
||||
Search-Outbox. `SEED_DEMO_PRO_WAIT_MS` ist nur für lokale Integrationsprüfungen
|
||||
gedacht; auf Staging bleibt der Standard bestehen.
|
||||
|
||||
Vor dem ersten Staging-Apply muss der neue Web-/Worker-Stand vollständig deployed und
|
||||
gesund sein. Erst dieser Stand versteht die Search-Batch-Aktionen und hält den
|
||||
Legacy-Boot-Seed über `SEED_DEMO_PRO_MANAGED=true` dauerhaft aus dem Pro-Tenant heraus.
|
||||
|
||||
Nach dem Outbox-Drain pollt der Lauf alle registrierten Meilisearch-Indizes mit
|
||||
Tenant-Filter. Der Tenant wird erst aktiviert, wenn CRM (976), Projekte (537),
|
||||
Aufgaben (1.684), Dateien (917) und Nutzer (50) vollständig sichtbar und alle
|
||||
anderen Tenant-Slices leer sind. Für die vollständig über die Search-API abrufbaren
|
||||
Slices bis 1.000 Dokumente wird zusätzlich die exakte ID-Menge geprüft. Der
|
||||
Aufgaben-Slice überschreitet Meilisearchs standardmäßige `maxTotalHits`-Grenze und
|
||||
wird deshalb fail-closed über die exakte Tenant-Facette und den vollständigen Count
|
||||
verifiziert.
|
||||
|
||||
Damit sich die geseedeten Demo-Konten anschließend auch anmelden können, muss auf
|
||||
der Staging-Web-Ressource `STAGING_DEMO_LOGIN_ENABLED=true` gesetzt sein (wirkt nur
|
||||
zusammen mit `SENTRY_ENVIRONMENT=staging`). Der Login-Schalter ist bewusst vom
|
||||
Seeding getrennt und trägt kein `SEED_`-Präfix: Der RLS-Deploy-Vertrag weist jeden
|
||||
`SEED_*`-Schlüssel auf Runtime-Ressourcen ab, weshalb der Login sonst nicht
|
||||
freischaltbar wäre.
|
||||
|
||||
Das gemeinsame Staging-Login-Passwort wird ausschließlich zur Laufzeit aus dem
|
||||
Secret-Store gelesen, muss mindestens 20 Zeichen lang und ausreichend zufällig
|
||||
sein und darf weder in Git noch in Deployment-Logs landen. Nur für den vom Owner
|
||||
explizit verlangten gemeinsamen Staging-Zugang akzeptiert der CLI exakt den
|
||||
vereinbarten Testwert, wenn zusätzlich
|
||||
`SEED_DEMO_PRO_ALLOW_SHARED_STAGING_PASSWORD=true` gesetzt ist. Das Flag gehört
|
||||
nicht in die Coolify-Runtime-Umgebung und erlaubt keinen anderen schwachen Wert.
|
||||
Der Seed nutzt in beiden Fällen denselben Argon2id-Hasher wie die App.
|
||||
|
||||
Vor dem Setzen von `SEED_DEMO_PRO_WORKERS_DRAINED=true` müssen Outbound- und
|
||||
Automations-Worker in Coolify pausiert und ihre aktiven Queue-Jobs vollständig
|
||||
abgearbeitet sein. `SEED_DEMO_PRO_OUTBOUND_SANDBOX=true` ist eine operative
|
||||
Nichtzustellbarkeits-Bestätigung und darf nur in einer der folgenden Lagen gesetzt
|
||||
werden:
|
||||
|
||||
1. Mail, SMS, Webhooks und Push zeigen nachweislich auf nicht zustellbare Test-Sinks.
|
||||
2. Fail-closed Isolation: Alle BullMQ-Queues außer `outbox.search-index` sind global
|
||||
pausiert, für jede pausierte Queue ist `active=0` bestätigt und die Coolify-Apps
|
||||
`worker-mail`, `worker-import`, `worker-webhook` und `worker-plugin` sind gestoppt.
|
||||
`worker-general` bleibt ausschließlich für DB-Outbox und Search-Acks aktiv; seine
|
||||
übrigen Queues bleiben ebenfalls global pausiert.
|
||||
|
||||
Die Isolation muss vor dem Apply erneut geprüft und bis zum erfolgreichen
|
||||
`--verify` gehalten werden. Der DB-Outbox-Reset kann bereits an BullMQ übergebene
|
||||
`DONE`-Jobs nicht zurückholen. Danach werden zuerst die pausierten Queues fortgesetzt
|
||||
und anschließend die vier Worker-Apps wieder gestartet. Der Search-Pfad bleibt für
|
||||
beide Search-Ack-Phasen durchgehend verfügbar.
|
||||
|
||||
Der Reset erhält Tenant, Subscription, Pro-Entitlements und globale Kataloge. Er
|
||||
ersetzt die fachlichen Projekt-, CRM-, Lead-, Aufgaben-, Datei-, Kalender-, Buchungs- und
|
||||
Search-Daten sowie die Tenant-Mitgliedschaften. Die 50 synthetischen Nutzer
|
||||
bleiben globale User-Zeilen und werden beim nächsten Lauf sicher aktualisiert. Die
|
||||
sieben SHK-Template-Rollen werden ebenfalls aus dem exakten Berechtigungskatalog
|
||||
neu aufgebaut, damit keine alte manuelle Zusatzberechtigung auf neue Testnutzer
|
||||
übergeht. Anschließend invalidiert der Lauf die Permission-Caches aller 50 Nutzer
|
||||
über den gemeinsamen Cache-Bus, bevor der Tenant wieder aktiviert werden kann.
|
||||
|
||||
Während `apply` und `cleanup` hält der Prozess eine DB-seitige Lease und setzt den
|
||||
Tenant in Wartung. Ein Heartbeat erneuert die Lease während aller Seed-,
|
||||
Outbox- und Search-Phasen; verliert der Prozess den Besitz, bricht er fail-closed
|
||||
ab. Nur ein vollständig verifizierter Apply-Lauf aktiviert den Tenant wieder.
|
||||
Nach Abbruch oder Fehler bleibt er absichtlich deaktiviert; zur Recovery denselben
|
||||
Apply-Befehl erneut ausführen. `cleanup` hinterlässt den leeren Tenant ebenfalls
|
||||
deaktiviert.
|
||||
|
||||
## Datenschutz und Zustellsicherheit
|
||||
|
||||
- Sämtliche E-Mail-Adressen liegen unter `.example.test`.
|
||||
- Sämtliche Telefonnummern liegen im offiziellen Frankfurter Drama-Number-Block
|
||||
`+49 69 90009 000–999`.
|
||||
- Orte und PLZ sind real; Straßen und Hausnummern sind synthetisch.
|
||||
- Die 917 Datei-Datensätze besitzen deterministisch erzeugte, minimale PDF-Objekte
|
||||
unter `tenants/{tenantId}/files/{fileId}/original`. Größe und SHA-256-Prüfsumme
|
||||
stammen aus den exakten Bytes. Da die PDFs ausschließlich im vertrauenswürdigen
|
||||
Seed-Prozess entstehen und nie Nutzereingaben oder Remote-Inhalte enthalten,
|
||||
werden sie als `clean` gespeichert; der AV-Gate für untrusted Uploads bleibt
|
||||
unverändert fail-closed. Vor jedem Reset löscht der Lauf den gesamten
|
||||
tenant-eigenen `files/`-Prefix, einschließlich verwaister Objekte aus älteren
|
||||
Katalogen oder abgebrochenen Läufen, in begrenzten Seiten von höchstens 1.000
|
||||
Keys. Die Abschlussprüfung verlangt die exakte erwartete Key-Menge und lehnt auch
|
||||
zusätzliche Objekte im verwalteten Prefix ab.
|
||||
- Direkte Dokumentbezüge werden nur bei eindeutiger Fachsemantik gesetzt: 81
|
||||
Rechnungen verweisen eins-zu-eins auf das gleichnamige Rechnungs-PDF und 13
|
||||
Abnahmen auf das Abnahmeprotokoll ihres Projekts. Checklisten-Fotos bleiben leer,
|
||||
weil der Katalog keine Bilddateien erzeugt. Plantafelzeilen erhalten nur dann
|
||||
`calendarEventId`/`synced`, wenn Projekt, Mitarbeiter und Zeitfenster exakt mit
|
||||
einem Kalendereintrag übereinstimmen; die getrennten Besprechungstermine des
|
||||
aktuellen Katalogs werden nicht als Montageeinsatz ausgegeben und deshalb nicht
|
||||
künstlich verknüpft.
|
||||
- Der Seed erzeugt keine E-Mails, SMS, Webhooks oder Push-Nachrichten.
|
||||
- Buchungsseiten bleiben unveröffentlicht, damit der öffentliche Staging-Tenant
|
||||
keine realen Terminanfragen oder Folge-E-Mails annimmt.
|
||||
|
||||
## Markt- und Geodaten
|
||||
|
||||
Die Verteilungen basieren auf folgenden Quellen:
|
||||
|
||||
- [ZVSHK Konjunktur Frühjahr 2026](https://www.zvshk.de/presse/medien-center/pressemitteilungen/shk-handwerk-verliert-an-dynamik): Bestandsanteil und Auftragsreichweite.
|
||||
- [VDS Kosten eines neuen Bads](https://www.sanitaerwirtschaft.de/aktuell/was-kostet-ein-neues-bad): Preis- und Laufzeitkorridore.
|
||||
- [ifeu Wärmepumpenkosten](https://www.ifeu.de/publikation/analyse-zu-kosten-fuer-material-und-einbau-von-waermepumpen-in-deutschland-und-ausgewaehlten-eu-mitgliedstaaten): Wärmepumpen-Retrofit-Korridore.
|
||||
- [Bundesnetzagentur Drama Numbers](https://www.bundesnetzagentur.de/DE/Fachthemen/Telekommunikation/Nummerierung/start.html): nicht zugeteilte Rufnummern.
|
||||
- [Geoportal Hessen, INSPIRE-Adressen](https://www.geoportal.hessen.de/spatial-objects/706): amtliche Straßennamen unter Datenlizenz Deutschland Zero 2.0.
|
||||
- [BfDI Kurzposition Testdaten](https://www.bfdi.bund.de/DE/Fachthemen/Inhalte/Technik/Kurzposition_Testdaten.html): Vorrang synthetischer Testdaten.
|
||||
|
||||
Der Geodaten-Check läuft getrennt vom Seed:
|
||||
|
||||
```bash
|
||||
pnpm seed:demo-pro:geodata
|
||||
```
|
||||
|
||||
Am 13.07.2026 wurden 92.178 amtliche hessische Straßennamen geprüft. Die 60
|
||||
generierten Straßenmuster hatten keine Kollision. Snapshot-Hash:
|
||||
`3678fccbbf62820aecc0a9c7c253e960123e2131a555aa7d4a3b0b2464a1fce3`.
|
||||
Da sich amtliche Daten ändern, ist der Check vor einem neuen Seed-Katalog erneut
|
||||
auszuführen.
|
||||
|
||||
## Verifikation
|
||||
|
||||
`--verify` prüft die vereinbarten Zielmengen einschließlich 17 Büro- und 33
|
||||
Feldmitarbeitern, die exakte Identitäts-, Rollen- und Dateimatrix in PostgreSQL,
|
||||
alle registrierten Meilisearch-Indizes sowie jedes
|
||||
der 917 realen S3-Objekte bytegenau gegen Größe und SHA-256. Dazu gehören drei
|
||||
Buchungsseiten, 35 Verfügbarkeitsregeln und 79 verknüpfte Buchungstermine. Ein erfolgreicher
|
||||
Apply-Lauf erzeugt außerdem 4.164 permission-aware Search-Projektionen und die
|
||||
entsprechenden, auf maximal 250 Dokumente gebündelten Outbox-Ereignisse für
|
||||
Meilisearch. Dadurch entstehen statt tausender Einzeljobs nur wenige Dutzend
|
||||
tenant-isolierte Batch-Jobs.
|
||||
|
||||
Zusätzlich schlägt die Verifikation fehl, sobald irgendein aktuelles tenant-bezogenes
|
||||
Modell mit `isDemoData` noch markierte Datensätze enthält, der sichtbare Tenant-Name
|
||||
nicht `RheinMain Gebäudetechnik GmbH` lautet oder die SHK-Rollen vom exakten
|
||||
Berechtigungskatalog abweichen.
|
||||
@@ -0,0 +1,523 @@
|
||||
# Customer-Portal: Erst-Rollout und Betrieb
|
||||
|
||||
Dieses Runbook beschreibt den sicheren Erst-Rollout von VA-P26a sowie die vorbereiteten
|
||||
VA-P26b-/VA-P26c-Verträge. Es enthält nur
|
||||
Schlüsselnamen und Platzhalter. Ressourcen-IDs, URLs mit Zugangsdaten, Passwörter,
|
||||
Tokens und Live-Konfiguration gehören ausschließlich in die freigegebenen Secret-
|
||||
und Betriebswerkzeuge.
|
||||
|
||||
**Stand 2026-07-22:** `VA-P26a`, `VA-P26b` und `VA-P26c` sind technisch vollständig. Der aktuelle
|
||||
Produkt- und UX-Vertrag einschließlich Tenant-Logo, Endkundenreisen und Designgrenzen steht in
|
||||
[`docs/features/customer-portal.md`](../features/customer-portal.md). PR `#212` wurde als Main-Revision
|
||||
`090e2558a6965e1c5804eb24d3eab5da8c8611a8` erfolgreich nach Staging ausgerollt. Core und Portal
|
||||
verwenden denselben Web-Digest; Health, Readiness, alle abhängigen Dienste und der revisionsgebundene
|
||||
Domain-Controller sind grün. Produktion wurde durch diesen UI-/Branding-Release nicht verändert.
|
||||
|
||||
| Ticket | Aktueller Stand | Formales Abschluss-Gate |
|
||||
| --------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| `VA-P26a` | 8/8 DoD = 100 % | technischer Handoff abgeschlossen; finaler Design-Polish bleibt `VD-P26` |
|
||||
| `VA-P26b` | 6/6 DoD = 100 % | technischer Handoff abgeschlossen; finaler Design-Polish bleibt `VD-P26` |
|
||||
| `VA-P26c` | 8/8 DoD = 100 % | technischer Handoff abgeschlossen; Produktion bleibt eine separate Freigabe |
|
||||
|
||||
## Abschlussnachweis des Basis-Deploys
|
||||
|
||||
- Feature-Merge: PR `#125`; Deploy-Hotfixes: PR `#130` und `#132`.
|
||||
- Finaler Lauf:
|
||||
[`#10300`](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/10300), exakte Revision
|
||||
`f54b04162b2823b1d2f6db0318baf1a7431c5b66`, vollständig grün für Staging und Produktion.
|
||||
- Forward-only Migration:
|
||||
`prisma/migrations/20260716123000_va_p26_customer_portal/migration.sql`, ausgeführt im
|
||||
einmaligen eingeschränkten Migrator-Container.
|
||||
- Migration-Chain-Parität, exakter Tenant-Policy-Vertrag, RLS-Release-Readiness und Live-RLS-
|
||||
Isolation waren grün. App, Worker und Portal verwenden getrennte Runtime-Rollen über PgBouncer.
|
||||
- `hivegrid-web` und `hivegrid-portal` liefen aus demselben gepinnten Image/Digest; beide bestanden
|
||||
`/healthz` und `/readyz` mit der erwarteten Revision. Hard-Caps und getrennte Pool-Limits waren
|
||||
Bestandteil des Deploy-Preflights.
|
||||
|
||||
Dieser Nachweis erfüllt das Merge-/RLS-Gate von VA-P26a/b. Er ersetzt nicht den UAT-Tenant,
|
||||
Browser-Klickpfade, Billing-Provider-Proof oder die VA-P26c-Controller-/Custom-Domain-/TLS-Gates.
|
||||
|
||||
## Zielbild
|
||||
|
||||
`hivegrid-web` und `hivegrid-portal` sind zwei getrennte Coolify-Ressourcen aus
|
||||
demselben unveränderlichen `hivegrid/web:<sha>`-Image und demselben Registry-Digest.
|
||||
Die Core-Ressource läuft als `hivegrid_app`; die Portal-Ressource ausschließlich als
|
||||
`hivegrid_portal`. Der Deploy-Workflow provisioniert weder die Portal-Ressource noch
|
||||
einen DNS-Eintrag; die bereits bestehende Worker-Reconciliation bleibt davon
|
||||
unberührt. Für den Portal-Rollout akzeptiert er nur vorab angelegte, eindeutig
|
||||
allowlistete Ressourcen und bricht bei Abweichungen vor dem Rollout ab.
|
||||
|
||||
Standardhosts:
|
||||
|
||||
- Staging: `staging-portal.hivegrid.de`
|
||||
- Produktion: `portal.hivegrid.de`
|
||||
- Kundeneigene Hosts wie `portal.geerkens.de` gehören zu VA-P26c. Claim, sichere Host-/Session-
|
||||
Auflösung und Admin-Self-Service sind lokal vorbereitet; eine Annahme im Live-Ingress erfolgt erst
|
||||
nach den unten beschriebenen Controller-, TLS-, Merge- und Staging-Gates.
|
||||
|
||||
## Harte Vorbedingungen vor dem Main-Merge
|
||||
|
||||
Der Main-Workflow prüft das Coolify-Inventar und die Runtime-Grenzen vor der
|
||||
Migration und bricht bei Abweichungen ohne Schemaänderung ab. Trotzdem müssen alle
|
||||
folgenden Punkte bereits vor dem Merge erfüllt sein:
|
||||
|
||||
1. Ein aktueller Backup-/Restore-Punkt ist bestätigt. Für Produktion ist zusätzlich
|
||||
ein dokumentierter Restore-Drill gemäß Estate-Standard erforderlich.
|
||||
2. `pnpm run db:roles:provision` wurde mit den fünf getrennten Passwort-Keys aus dem
|
||||
Secret-Store ausgeführt. `hivegrid_portal` ist danach `LOGIN`, `NOINHERIT`,
|
||||
`NOBYPASSRLS`, kein Superuser und hat keine Rollenmitgliedschaft.
|
||||
3. PgBouncer enthält einen eigenen SCRAM-Eintrag für `hivegrid_portal`, wurde neu
|
||||
geladen und akzeptiert den Portal-Login. Details stehen in
|
||||
[`docs/ops/pgbouncer.md`](../ops/pgbouncer.md).
|
||||
4. `hivegrid-portal` ist in Staging gestoppt beziehungsweise noch nicht öffentlich
|
||||
erreichbar angelegt, verwendet dasselbe Web-Image wie `hivegrid-web` und steht in
|
||||
der Staging-Ressourcen-Allowlist. Vor einer Produktion-Promotion gilt dasselbe für
|
||||
Produktion.
|
||||
5. Bestehende Runtime-Ressourcen enthalten weder `DIRECT_URL`, `MIGRATE_ON_BOOT`,
|
||||
`SEED_ON_BOOT`, `SEED_*` noch `MIGRATOR_*`. Diese Schlüssel gehören nur in den
|
||||
kurzlebigen Migrationsschritt.
|
||||
6. Core-Web und Portal haben in Coolify jeweils positive, explizite Hard-Caps in
|
||||
`limits_cpus` und `limits_memory`; Portal und Core haben getrennte
|
||||
PgBouncer-Zugangsdaten und bewusst gesetzte Pool-Limits. `0`/`unlimited`, nur
|
||||
`limits_cpu_shares` oder nur eine Memory-Reservation zählen nicht als Hard-Cap.
|
||||
Für den ersten Produktionsrollout sind Core mit 2 vCPU/2 GB und
|
||||
`DATABASE_POOL_MAX=10` sowie Portal mit 1 vCPU/1 GB und
|
||||
`DATABASE_POOL_MAX=5` je Prozess/Instanz festgelegt. Spätere Anpassungen erfolgen
|
||||
nur anhand gemessener Last und bleiben als explizite Hard-Caps dokumentiert.
|
||||
7. `worker-mail` erhält denselben `PORTAL_APP_HOST` wie die Portal-Ressource, damit
|
||||
Status-Mails keine aus `APP_BASE_DOMAIN` abgeleitete falsche URL erzeugen.
|
||||
8. `worker-mail` erhält exakt denselben `CRYPTO_SECRET` wie `hivegrid-web`. Ohne
|
||||
diesen gemeinsamen Envelope-Key müssen Worker-Start, Healthcheck und Deploy-Preflight
|
||||
fail-closed abbrechen; der Wert darf nie geloggt werden.
|
||||
9. `worker-general` erhält `LAGO_API_URL`, `LAGO_API_KEY`, `LAGO_TIMEOUT_MS`,
|
||||
`MOLLIE_API_KEY`, `MOLLIE_PROFILE_ID` und `MOLLIE_TIMEOUT_MS` aus dem
|
||||
freigegebenen Coolify-Secret-/Env-Source. Fehlende Provider-Keys oder
|
||||
ungültige gesetzte Timeouts müssen im Deploy-Preflight beziehungsweise beim
|
||||
Required-RLS-Start fail-closed abbrechen. `MOLLIE_PROFILE_ID` bleibt optional.
|
||||
10. `hivegrid-web`, `hivegrid-portal`, `worker-import` und `worker-general`
|
||||
verwenden denselben privaten Bucket sowie dieselben normalisierten Werte für
|
||||
`STORAGE_ENDPOINT`, `STORAGE_REGION`, `STORAGE_BUCKET` und
|
||||
`STORAGE_FORCE_PATH_STYLE`. Ein vorhandenes gemeinsames
|
||||
`STORAGE_ACCESS_KEY_ID`-/`STORAGE_SECRET_ACCESS_KEY`-Paar ist für alle vier
|
||||
Ressourcen zulässig und kein Rollout-Blocker; getrennte Credentials bleiben
|
||||
optional. Nur Core, Portal und Import-Worker erhalten exakt denselben
|
||||
`GDPR_EXPORT_SSE_C_KEY_BASE64`;
|
||||
der reine Lösch-Worker benötigt und erhält diesen Customer-Key nicht.
|
||||
`STORAGE_SESSION_TOKEN` wird nur gesetzt, wenn das jeweilige Credential ihn
|
||||
tatsächlich benötigt. Fehlende Pflichtwerte, ein nicht-HTTPS-Endpoint oder
|
||||
ein nicht kanonisch Base64-kodierter 32-Byte-Key brechen den
|
||||
Produktionsstart fail-closed ab.
|
||||
Die lokale Staging-Compose-Referenz bildet dieselbe Konfiguration über die
|
||||
host-seitigen Quellen `WEB_STORAGE_*`, `WORKER_IMPORT_STORAGE_*` und
|
||||
`WORKER_GENERAL_STORAGE_*`; diese Quellen dürfen auf dasselbe Credential
|
||||
zeigen. Die Portal-Ressource bleibt eine separate Coolify-Resource mit
|
||||
vollständig gesetzten `STORAGE_*`-Werten. Der Deploy-Preflight prüft
|
||||
Vollständigkeit und gemeinsame Storage-Zielwerte, vergleicht oder protokolliert
|
||||
die Credential-Werte jedoch nicht.
|
||||
`worker-import` und `worker-general` müssen für die gemeinsame
|
||||
Tenant-Export-Barriere außerdem denselben normalisierten Redis-Endpunkt und
|
||||
dieselbe Redis-Datenbank verwenden. Dafür gilt effektiv ein nichtleeres
|
||||
`REDIS_URL`, sonst `BULLMQ_REDIS_URL`; Zugangsdaten dürfen getrennt sein.
|
||||
Fehlende, ungültige oder abweichende Ziele brechen den Deploy-Preflight ab,
|
||||
ohne Redis-URLs auszugeben.
|
||||
11. `worker-general` erhält zusätzlich `MEILI_URL` und den HiveGrid-scoped
|
||||
`MEILI_API_KEY`. In Production, required-RLS sowie Staging-/Production-Sentry
|
||||
muss der Worker vor Queue-Ownership abbrechen, wenn Wert oder Search-Client
|
||||
fehlen; ein Tenant-Hard-Delete darf sonst nicht erfolgreich abschließen.
|
||||
|
||||
## Runtime-Matrix
|
||||
|
||||
| Bereich | `hivegrid-web` | `hivegrid-portal` | `worker-mail` |
|
||||
| --------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
||||
| Surface | `WEB_RUNTIME_SURFACE=core` | `WEB_RUNTIME_SURFACE=portal` | nicht setzen |
|
||||
| DB-Rolle | `DATABASE_RUNTIME_ROLE=hivegrid_app` | `DATABASE_RUNTIME_ROLE=hivegrid_portal` | `DATABASE_RUNTIME_ROLE=hivegrid_worker` |
|
||||
| DB-Modus | `RLS_RUNTIME_MODE=required` | `RLS_RUNTIME_MODE=required` | `RLS_RUNTIME_MODE=required` |
|
||||
| Produktions-Pool je Instanz | `DATABASE_POOL_MAX=10` | `DATABASE_POOL_MAX=5` | nach Worker-Vertrag |
|
||||
| Produktions-Hard-Cap | 2 vCPU / 2 GB RAM | 1 vCPU / 1 GB RAM | nach Worker-Vertrag |
|
||||
| Session | `SESSION_SECRET` | `PORTAL_SESSION_SECRET` | keine Web-Session |
|
||||
| Tenant-Envelope-Key | `CRYPTO_SECRET` | nicht erforderlich | exakt derselbe `CRYPTO_SECRET` wie `hivegrid-web` |
|
||||
| Portalhost | `PORTAL_APP_HOST` | `PORTAL_APP_HOST` | `PORTAL_APP_HOST` |
|
||||
| Custom-Domain-Runtime | in Staging exakt `PORTAL_CUSTOM_DOMAIN_RUNTIME_ENABLED=true`; Produktion bis zum freigegebenen Controller unset/false | identischer expliziter Staging-Opt-in; Produktion bis zur Freigabe unset/false | nicht setzen |
|
||||
| Redis | nach Core-Funktion | gültiges `REDIS_URL`; optional gültiges `BULLMQ_REDIS_URL` | Queue-Verbindung nach Worker-Vertrag |
|
||||
| GDPR-Export-Storage | gemeinsamer Endpoint/Region/Bucket, vollständiges Storage-Credential; gemeinsames Paar zulässig | gemeinsamer Endpoint/Region/Bucket, vollständiges Storage-Credential; gemeinsames Paar zulässig | nicht setzen |
|
||||
| GDPR-Export-SSE-C | `GDPR_EXPORT_SSE_C_KEY_BASE64`, exakt wie im Import-Worker | exakt derselbe Wert wie `hivegrid-web` und Import-Worker | nicht setzen |
|
||||
| CAPTCHA | Core-Konfiguration | `CAPTCHA_PROVIDER=cap` oder `mcaptcha` plus passende Login-Keys und Instanz-URL | nicht erforderlich |
|
||||
| Auth-Mail | Core-Mailkonfiguration | nur Queue-Verbindung; keine Mailjet-Provider-Credentials | Mailjet-Absender-/Provider-Keys für Auth- und Status-Mails plus Queue-Verbindung |
|
||||
| Admin SSO/OAuth/Billing | nur dort, wo der Core-Vertrag es erlaubt | verboten | nach eigenem Worker-Vertrag, nie Portal-Credentials |
|
||||
|
||||
Auf `hivegrid-portal` sind zusätzlich alle Core-Session-, Authentik-, OAuth-, Billing-,
|
||||
Coolify-, SSH-, Traefik-, Ingress-, Cloudflare-, Domain-Controller- und veralteten
|
||||
`PORTAL_SERVER_*`-Keys verboten. `APP_REVISION` wird aus dem Image gelesen und darf
|
||||
nicht als Coolify-Override existieren.
|
||||
|
||||
### GDPR-Export-Storage: Schlüssel und effektive Rechte
|
||||
|
||||
Der dedizierte Import-Worker schreibt Portal- und Privacy-Exporte mit SSE-C. Beide
|
||||
Web-Surfaces lesen sie ausschließlich serverseitig mit demselben Customer-Key; es
|
||||
gibt keinen Presigned-URL- oder Klartext-Fallback. Die S3-Zugangsdaten dürfen von
|
||||
den vier Runtimes geteilt werden; getrennte Principals sind optional und werden
|
||||
nicht vom Deploy-Preflight erzwungen. Für die Anwendungspfade gilt diese
|
||||
Funktionsmatrix:
|
||||
|
||||
| Runtime | Erlaubte Object-Actions | Erlaubte Object-ARNs/Key-Prefixe | Explizit nicht benötigt |
|
||||
| ------- | ----------------------- | -------------------------------- | ----------------------- |
|
||||
| `hivegrid-web` | `s3:GetObject` | `arn:aws:s3:::<bucket>/gdpr-exports/privacy/tenants/*/*/*` | Portal-GDPR-Prefix, `s3:PutObject`, `s3:DeleteObject`, `s3:ListBucket` |
|
||||
| `hivegrid-portal` | `s3:GetObject` | `arn:aws:s3:::<bucket>/gdpr-exports/portal/tenants/*/*/*` | Core-GDPR-Prefix, `s3:PutObject`, `s3:DeleteObject`, `s3:ListBucket` |
|
||||
| `worker-import` | `s3:PutObject`; zusätzlich `s3:DeleteObject` nur nach einem eindeutig fehlgeschlagenen Attempt, niemals bei unklarem Commit-Ausgang oder Owner-CAS-Verlust | beide oben genannten Object-Prefixe | `s3:GetObject`, `s3:ListBucket` |
|
||||
| `worker-general` | `s3:DeleteObject`; bucket-level `s3:ListBucket` nur mit `s3:prefix`-Condition auf `tenants/*`, `gdpr-exports/privacy/tenants/*` und `gdpr-exports/portal/tenants/*` | beide oben genannten Object-Prefixe sowie der bestehende Hard-Delete-Prefix `arn:aws:s3:::<bucket>/tenants/*` | Customer-Key, `s3:GetObject`, `s3:PutObject`, unbeschränktes `s3:ListBucket` |
|
||||
|
||||
Bei einem gemeinsamen Credential benötigt dessen Bucket-Policy die Vereinigungsmenge
|
||||
der in der Tabelle aufgeführten Actions und Prefixe. Die Trennung der App-Pfade
|
||||
bleibt im Code erhalten, ist dann aber keine Principal-Isolation des Providers.
|
||||
`worker-general` erhält unabhängig davon nie den SSE-C-Customer-Key und kann die
|
||||
Exportinhalte deshalb nicht entschlüsseln. Falls das Credential weitere, bereits
|
||||
freigegebene Storage-Funktionen bedient, erhalten diese eigene, explizite Statements
|
||||
auf deren Prefixe; daraus darf kein `s3:*` auf dem gesamten Bucket entstehen. Alle
|
||||
Artefakte liegen im gemeinsamen, export-first Keyspace
|
||||
`gdpr-exports/`; jeder Versuch erhält einen eigenen `attemptId`, sodass ein später
|
||||
oder parallel verlorener Versuch nicht das veröffentlichte Artefakt überschreibt.
|
||||
Der private Export-Bucket verwendet für diese Objekte weder Versioning noch Object
|
||||
Lock, weil der aktuelle `DeleteObject`-Pfad sonst nur einen Delete-Marker setzen
|
||||
beziehungsweise an einer Retention scheitern könnte. Die Bucket-Policy ist
|
||||
default-deny für andere Principals, Actions und Prefixe.
|
||||
|
||||
Als Defense-in-depth liegt auf exakt dem Prefix `gdpr-exports/` zusätzlich eine
|
||||
Provider-Lifecycle-Regel mit `Expiration.Days=3`. Sie schützt auch dann vor
|
||||
dauerhaft liegen gebliebenen Attempts, wenn App-Kompensation und beide Sweeper
|
||||
ausfallen. Sie ist kein Ersatz für den 15-Minuten-Sweep und keine Zusage einer
|
||||
minutengenauen Löschung: Hetzner verarbeitet Lifecycle-Expiration asynchron. Die
|
||||
Regel darf weder den übrigen Bucket noch andere Prefixe erfassen. Hetzner
|
||||
dokumentiert action-spezifische Bucket-Policies, SSE-C und Lifecycle-Regeln; das
|
||||
Repository kann ihre tatsächlich angewandte Provider-Konfiguration jedoch nicht
|
||||
allein beweisen ([S3-Credentials](https://docs.hetzner.com/storage/object-storage/faq/s3-credentials/),
|
||||
[SSE-C](https://docs.hetzner.com/storage/object-storage/howto-protect-objects/encrypt-with-sse-c/),
|
||||
[Lifecycle](https://docs.hetzner.com/storage/object-storage/howto-protect-objects/manage-lifecycle/),
|
||||
[unterstützte Actions](https://docs.hetzner.com/storage/object-storage/supported-actions/)).
|
||||
|
||||
Privacy-Exporte sind nach `resultExpiresAt` höchstens 72 Stunden, Portal-Exporte
|
||||
höchstens 24 Stunden über die authentifizierte App-Route abrufbar. Die Route sperrt
|
||||
den Zugriff ab diesem Zeitpunkt sofort. Der erforderliche Lösch-Scheduler läuft im
|
||||
15-Minuten-Takt; physisch gelöscht wird im ersten erfolgreichen Sweep nach Ablauf.
|
||||
Die planmäßige Löschlatenz beträgt damit bis zu 15 Minuten zuzüglich Laufzeit, ist
|
||||
bei Provider-/Queue-Störung aber ausdrücklich nicht garantiert. Fehler müssen den
|
||||
Job fehlschlagen lassen, erneut versucht werden und bis zur erfolgreichen Löschung
|
||||
als Alarm offen bleiben. Eindeutig fehlgeschlagene Attempts werden unmittelbar
|
||||
kompensiert. Bei unklarem PUT- oder Ready-CAS-Ausgang bleiben Claim und Pointer
|
||||
erhalten, damit der Retry denselben Key übernimmt; der Sweep erfasst zusätzlich
|
||||
deterministisch adressierbare verwaiste Artefakte.
|
||||
|
||||
Bei einer Rotation werden Import-Worker, Core und Portal gemeinsam umgestellt,
|
||||
nachdem alle mit dem alten Customer-Key verschlüsselten Exportobjekte erfolgreich
|
||||
gelöscht wurden. Im Dedicated-Modus setzt der Import-Worker
|
||||
`PORTAL_GDPR_EXPORT_QUEUE_ENABLED=true` und hält `IMPORT_QUEUE_ENABLED=false` sowie
|
||||
`IMPORT_QUEUE_RUNTIME_READY=false`; eine Mischkonfiguration bricht Runtime- und
|
||||
Deploy-Preflight fail-closed ab. Der alternative Full-Modus setzt beide
|
||||
`IMPORT_QUEUE_*`-Gates auf `true` und hält
|
||||
`PORTAL_GDPR_EXPORT_QUEUE_ENABLED` unset oder `false`. Auch dann bleiben der
|
||||
Storage-/SSE-C-Vertrag sowie Portal-, Privacy- und generische
|
||||
Import-/Export-Service-Wirings verpflichtend. Im Idle-Modus bleiben alle drei Gates
|
||||
unset oder `false`; dann darf der Import-Worker seinen Storage-/SSE-C-Vertrag
|
||||
weglassen und konsumiert keine Import-/Export-Queue. Core und Portal behalten ihren
|
||||
verschlüsselten Downloadvertrag unabhängig davon. `worker-general` setzt in jedem
|
||||
Staging-/Produktions-Rollout `EXPORT_RETENTION_QUEUE_ENABLED=true` und startet nicht
|
||||
bereit, wenn Scheduler, Redis oder sein Delete-only-Storage-Vertrag fehlen. Ein
|
||||
gesetzter `GDPR_EXPORT_SSE_C_KEY_BASE64` ist auf diesem Lösch-Worker ausdrücklich
|
||||
verboten und wird von Runtime- und Deploy-Preflight zurückgewiesen.
|
||||
|
||||
### Operator-Checkpoint: Provider-Vertrag
|
||||
|
||||
Unit-Tests und der Coolify-Preflight beweisen nur Key-Format, Env-Vollständigkeit,
|
||||
gemeinsamen Bucket/Endpoint und die Runtime-Verdrahtung. Sie beweisen weder die
|
||||
aktive Hetzner-Bucket-Policy noch SSE-C- oder Hard-Delete-Semantik. Vor jedem neuen
|
||||
Environment und nach jeder Policy-/Credential-Rotation führt ein Operator deshalb
|
||||
mit ausschließlich wegwerfbaren Testobjekten den folgenden redigierten Check aus:
|
||||
|
||||
1. Privaten Bucket, default-deny Policy sowie deaktiviertes Versioning/Object Lock
|
||||
bestätigen. Die aktive Lifecycle-Konfiguration muss genau ein
|
||||
`Expiration.Days=3`-Statement für `gdpr-exports/` enthalten und darf keinen
|
||||
breiteren Prefix erfassen. Policy-/Lifecycle-Hash und Prüfzeitpunkt
|
||||
dokumentieren, nie Schlüsselwerte.
|
||||
Vor dem ersten SSE-C-Rollout zusätzlich die Legacy-Keyspaces
|
||||
`tenants/*/gdpr/*.zip` und `tenants/*/portal-gdpr/*/*.json` mit einem separat
|
||||
verwahrten Operator-Credential inventarisieren, vollständig löschen und die
|
||||
dazugehörigen DB-Jobs auf `expired` setzen beziehungsweise ihre alte
|
||||
Objektadresse entfernen. Nur redigierte Counts, Policy-Hash und Prüfzeitpunkt
|
||||
dokumentieren. Der neue Reader darf diese Klartextobjekte nie als Fallback
|
||||
akzeptieren.
|
||||
2. Mit dem konfigurierten Storage-Credential je ein Lese- und ein
|
||||
Kompensations-Testobjekt mit SSE-C in beide GDPR-Prefixe schreiben und die
|
||||
Kompensationsobjekte wieder löschen. Für den GDPR-Keyspace müssen Actions und
|
||||
Prefixe außerhalb der oben beschriebenen Export-/Hard-Delete-Matrix scheitern;
|
||||
außerhalb dieses Keyspaces gilt die vollständig inventarisierte
|
||||
Vereinigungsmenge aller für das gemeinsame Credential explizit freigegebenen
|
||||
Actions und Prefixe.
|
||||
3. Über die authentifizierten App-Routen bestätigen, dass Core nur das
|
||||
Privacy-Objekt und Portal nur das Portal-Objekt mit Customer-Key ausliefert.
|
||||
Kreuz-Prefix sowie Abruf ohne oder mit falschem Customer-Key müssen scheitern.
|
||||
Ein gemeinsamer Provider-Principal wird hierbei bewusst nicht als
|
||||
Runtime-Isolation gewertet.
|
||||
4. `worker-general` muss die drei für Tenant-Hard-Delete benötigten Prefixe
|
||||
(`tenants/{tenantId}/`, Privacy-Export, Portal-Export) listen und darin
|
||||
löschen können. Der Worker darf keinen `GDPR_EXPORT_SSE_C_KEY_BASE64` erhalten
|
||||
und bietet ausschließlich den Delete-/Retention-Pfad an. Bei einem gemeinsamen
|
||||
Storage-Credential ist eine providerseitige Get-/Put-Sperre für diesen einzelnen
|
||||
Prozess nicht nachweisbar; verpflichtend bleiben die Prefix-Grenzen der
|
||||
Bucket-Policy. Danach wird bestätigt, dass die Objekte fehlen.
|
||||
5. Je ein isoliertes, kurz vor Ablauf datiertes UAT-Fixture für Privacy und Portal
|
||||
beobachten: App-Download ab Expiry abgewiesen, Artefakt im
|
||||
ersten erfolgreichen 15-Minuten-Sweep gelöscht, Alarmweg bei einem absichtlich
|
||||
fehlgeschlagenen Delete anschließend wieder resolved. Das Fenster im
|
||||
Produktvertrag bleibt 72 beziehungsweise 24 Stunden; nur dieser Live-
|
||||
Checkpoint zählt als Provider-Proof.
|
||||
6. Ein ausschließlich für den Backstop erzeugtes Attempt unter `gdpr-exports/`
|
||||
liegen lassen und nach Ablauf der dreitägigen Provider-Regel mit dem separaten
|
||||
Operator-Credential seine Entfernung bestätigen. Das Ergebnis ist ein
|
||||
zeitversetzter Provider-Nachweis und blockiert nicht den primären App-Sweep-
|
||||
Checkpoint; bis zur Bestätigung bleibt es als offener Betriebsnachweis markiert.
|
||||
|
||||
## VA-P26c: privater Domain-Controller-Vertrag
|
||||
|
||||
Die vorbereitete private Ressource heißt `hivegrid-portal-domain-controller` und verwendet das
|
||||
gleichnamige immutable Image/Target mit derselben expliziten Revision wie der freigegebene
|
||||
Portal-Release. Sie ist nicht öffentlich erreichbar und besitzt ausdrücklich **keine** Datenbank-,
|
||||
Coolify-, SSH-, Root-, Cloudflare-, allgemeine Traefik-/Ingress- oder Docker-Socket-Credentials.
|
||||
Benötigt werden ausschließlich:
|
||||
|
||||
- eine eigene Redis-Verbindung für die dedizierten signierten Command-/Result-Queues;
|
||||
- ein getrenntes Command-Secret sowie ein getrenntes Bearer-Token für `/metrics`;
|
||||
- DNS-/HTTPS-Outbound für Ownership-, CNAME-, SNI- und Health-Prüfungen;
|
||||
- Schreibrecht ausschließlich auf
|
||||
`/data/coolify/proxy/dynamic/hivegrid-portal-domains/`, nicht auf das übergeordnete
|
||||
Dynamic-Config-Verzeichnis;
|
||||
- das environment-spezifische, provider-qualifizierte Coolify-Ziel
|
||||
`https-0-<hivegrid-portal-uuid>@docker`; ein frei wählbares oder provider-loses Backend ist
|
||||
verboten.
|
||||
|
||||
Commands tragen `claimId`, `tenantId`, `generation`, `hostname` und `action` sowie Signatur und
|
||||
Content-Hash. Der Controller verwirft falsche Signaturen, alte Generationen und nicht exakte Hosts.
|
||||
Traefik-Dateien werden über Temp-Datei, `fsync` und atomaren Rename geschrieben; jede Regel matcht
|
||||
exakt `Host()` und verwendet kein offenes On-Demand-Wildcard-TLS. `active` darf erst nach realem
|
||||
SNI-/Portal-Health-Ack gesetzt werden. Dafür läuft ausschließlich der schmale
|
||||
`hivegrid_portal_resolve_custom_hostname_health`-Resolver vor dem normalen Host-Dispatch: Er akzeptiert
|
||||
nur DNS-verifizierte Claims mit aktivem Entitlement/Payment, persistiertem Controller-Command und
|
||||
Domainstatus `provisioning`, `active` oder `degraded`; pending, disabled, Kill-Switch und
|
||||
Deprovisioning liefern 404. Das ist ein Controller-Probe, keine Freigabe für pre-active Portalinhalte.
|
||||
`/healthz` bleibt ohne Secrets nutzbar, `/metrics` ist Bearer-geschützt.
|
||||
|
||||
Das Repository enthält Image-, CI-/SBOM-, Health-, Queue- und Renderer-Verträge. Das ist kein Beleg,
|
||||
dass die Ressource in Coolify angelegt, gestartet oder mit dem Estate-Traefik verbunden wurde.
|
||||
Bis dieser Beleg je Environment vorliegt, bleibt `PORTAL_CUSTOM_DOMAIN_RUNTIME_ENABLED` dort unset
|
||||
oder `false`. Nur Staging setzt den Wert aktuell auf exakt `true`, und zwar auf `hivegrid-web` sowie
|
||||
`hivegrid-portal`; der Coolify-Helper prüft beide Werte vor jeder Controller-Mutation. Das Gate
|
||||
blendet den Tenant-Admin-Link aus und liefert für Domain-Admin-Route sowie Custom-Host-Routing 404,
|
||||
ohne den Standardhost des Kundenportals abzuschalten.
|
||||
|
||||
## Merge-Migration
|
||||
|
||||
Auf dem Feature-Branch blieb `verify:migrations-parity` gemäß AD-21 absichtlich rot. Für den Merge
|
||||
wurde daraus genau eine reviewte forward-only P26-Migration für den ausgewählten gemeinsamen
|
||||
Portal-Vertragsstand aus VA-P26a/b/c erzeugt:
|
||||
`prisma/migrations/20260716123000_va_p26_customer_portal/migration.sql`. Der rohe Prisma-Diff wurde
|
||||
nicht ungeprüft übernommen; auf dem Feature-Branch gab es ausdrücklich keine eigene Migration.
|
||||
|
||||
### Bestandsdaten-Preflight
|
||||
|
||||
Die Migration muss vor jeder destruktiven Änderung fail-closed prüfen:
|
||||
|
||||
- `Portal.tenantId` ist lückenlos und verweist auf den richtigen Tenant.
|
||||
- Pro Tenant existiert höchstens ein Portal, bevor der neue Unique-Index entsteht.
|
||||
- `PortalUser.tenantId` ist lückenlos und entspricht immer dem Tenant seines Portals.
|
||||
- Portal-E-Mails sind nach `lower(trim(email))` weder leer noch innerhalb eines
|
||||
Portals doppelt.
|
||||
- Die später benötigten zusammengesetzten IDs/FKs zwischen Portal, PortalUser,
|
||||
Projekt, Stage und File sind tenant-konsistent.
|
||||
- Das freigegebene Legacy-Mapping ist anwendbar: tenant-konsistente PortalUser mit
|
||||
einem nichtleeren, vom aktuellen Passwort-Hasher akzeptierten `passwordHash`
|
||||
werden `active`; alle übrigen übernahmefähigen PortalUser werden `invited`.
|
||||
Bestehende Hashes werden byte-identisch erhalten und niemals neu gehasht oder
|
||||
durch ein Default-Passwort ersetzt. `emailVerifiedAt` wird nur aus einem vor dem
|
||||
Cutover dokumentierten, belastbaren Verifikationsbeleg übernommen. Ein fehlender
|
||||
Legacy-`verifyToken` allein zählt nicht als Beleg und führt deshalb zu `NULL`.
|
||||
|
||||
Fehlerhafte oder mehrdeutige Zeilen werden nicht geraten, automatisch gelöscht oder
|
||||
unter einem beliebigen Tenant einsortiert. Sie müssen vor dem Cutover bewusst
|
||||
bereinigt beziehungsweise zugeordnet werden.
|
||||
|
||||
### Token- und Re-Invite-Entscheidung
|
||||
|
||||
Die alten Felder `PortalUser.verifyToken` und `PortalUserRegistration.token` enthalten
|
||||
keinen mit dem neuen `PortalToken`-Vertrag kompatiblen Hash. Sie werden nicht in
|
||||
gültige neue Login-Fähigkeiten umgewandelt. Offene Registrierungen beziehungsweise
|
||||
alte Verify-Tokens werden invalidiert; betroffene Personen erhalten nach dem Cutover
|
||||
einen neuen Setup-/Magic-Link über den geprüften Flow. Dieser Re-Invite muss vor dem
|
||||
Drop fachlich freigegeben und kommuniziert sein.
|
||||
|
||||
Die Migration bricht vor jeder Mutation ab, sobald Tenant-/Portal-Zuordnung,
|
||||
normalisierte E-Mail oder Portal-Owner nicht eindeutig sind. Sie archiviert oder
|
||||
verschiebt keine Konfliktzeile automatisch. Legacy-Registrierungen und Tokens werden
|
||||
vollständig invalidiert; weder Klartext- noch Legacy-Tokenwerte dürfen in die neuen
|
||||
`PortalToken`-Zeilen gelangen.
|
||||
|
||||
### DDL- und Policy-Reihenfolge
|
||||
|
||||
Die Migration führt Preflight, Backfill, Constraints, Tabellenänderungen und RLS in
|
||||
einer atomaren Migration aus:
|
||||
|
||||
1. Fehlende `tenantId`-/`emailNormalized`-/Locale-Werte nach dem freigegebenen
|
||||
Mapping backfillen und die Preflight-Prüfungen erneut ausführen.
|
||||
2. Die sieben geprüften Legacy-Commerce-Policies sowie die Policy von
|
||||
`PortalUserRegistration` explizit entfernen.
|
||||
3. Acht Legacy-Tabellen FK-sicher child-first entfernen:
|
||||
`PortalUserSubscriptionProductPrice`, `PortalUserSubscriptionProduct`,
|
||||
`PortalSubscriptionFeature`, `PortalSubscriptionPrice`,
|
||||
`PortalUserSubscription`, `PortalSubscriptionProduct`,
|
||||
`PortalCheckoutSessionStatus` und `PortalUserRegistration`.
|
||||
4. Den vollständigen aktuellen Portal-Vertragsstand anlegen: Auth/Session/Token,
|
||||
ProjectAccess/Stage-/Dokumentfreigabe/Status-Mail, Upload/Reklamation,
|
||||
Subunternehmerzugang, Tenant-Konfiguration/Auto-Release/Notification-Präferenzen,
|
||||
Service-Inbox/Routing, DSGVO-Export/Löschung/Lifecycle sowie Domain-Claim und aktuelle
|
||||
Custom-Domain-State-Machine. Dazu gehören alle Enums, Indizes, zusammengesetzten Tenant-FKs und
|
||||
die sicheren Änderungen an `Portal`/`PortalUser`; eine fest verdrahtete Annahme von nur „sechs
|
||||
Portal-Tabellen" ist veraltet.
|
||||
5. Nur den noch nicht migrierten Portal-Delta für die normalen `hivegrid_app`-/
|
||||
`hivegrid_worker`-Tenant-Policies einbetten. Bereits migrierte Telephony-Objekte
|
||||
dürfen nicht aus einem breiten Generator-Delta dupliziert werden.
|
||||
6. Die schmalen `hivegrid_portal`-Policies, Spalten-Grants und
|
||||
`SECURITY DEFINER`-Resolver einbetten. Die Actor-Invarianten erzwingen für `File`,
|
||||
`FileUpload`, `FileEntityLink` und `portal_form`-`FormSubmission` genau den zulässigen internen
|
||||
oder Portal-Aktor. Die schmalen Domain-Controller-Capabilities bleiben vom Portal-Login getrennt.
|
||||
SQL-Dateien mit eigenem `BEGIN`/`COMMIT`
|
||||
werden nicht blind verkettet; beim Einbetten bleibt genau eine äußere Transaktion.
|
||||
|
||||
Der Inverse-SQL-Kommentar rekonstruiert Struktur, Indizes, FKs, Grants und Policies
|
||||
parent-first. Er weist ausdrücklich darauf hin, dass gelöschte Registrierungs- und
|
||||
Commerce-Zeilen nur aus dem Backup, nicht durch Inverse-DDL, wiederhergestellt werden.
|
||||
|
||||
### Pflicht-Proof der Migration
|
||||
|
||||
Vor dem Merge beziehungsweise Rollout müssen grün sein:
|
||||
|
||||
```sh
|
||||
pnpm exec prisma validate
|
||||
pnpm run verify:migrations-parity
|
||||
HIVEGRID_RLS_REQUIRE_MIGRATION_CHAIN_PARITY=1 pnpm run verify:rls-live
|
||||
pnpm run verify:tenant-policy-contract
|
||||
pnpm run verify:rls-release-readiness
|
||||
```
|
||||
|
||||
Der strikte RLS-Lauf muss eine frische leere Datenbank ausschließlich mit
|
||||
`prisma migrate deploy` aufbauen. `prisma db push`, der Feature-Branch-Recut-Helper
|
||||
und manuell nachgeladene Policy-Dateien sind in diesem Proof verboten.
|
||||
|
||||
### Lokaler Merge-Kandidaten-Proof vom 2026-07-16
|
||||
|
||||
Ein **bewusst ungetrackter lokaler Merge-Kandidaten-Proof** wurde gegen zwei wegwerfbare
|
||||
PostgreSQL-16-Datenbanken ausgeführt. Die zugehörigen Repository-Verträge liegen in `18dfd4825`;
|
||||
der temporäre Migrationskandidat selbst wurde gemäß AD-21 nicht in der Feature-Branch committed:
|
||||
|
||||
1. leere Datenbank nach vollständigem `prisma migrate deploy` der bestehenden Chain;
|
||||
2. Datenklon mit den acht Legacy-Commerce-/Registrierungstabellen und repräsentativen PortalUsern.
|
||||
|
||||
Beide Läufe verwendeten den eingeschränkten `hivegrid_migrator` und endeten schema-paritätisch zum
|
||||
aktuellen Prisma-Schema. Der Legacy-Klon bestätigt `active` für akzeptierte Hashes, `invited` für
|
||||
nicht akzeptierte/fehlende Hashes, byte-identische Hash-Erhaltung, `emailNormalized`-/Tenant-/Locale-
|
||||
Backfill und Reset nicht belastbar belegter Verifikation sowie alter Registrierung/Token-Fähigkeiten.
|
||||
Eine normalisierte Duplicate-E-Mail-Kollision bricht fail-closed vor Mutation ab. Vier Actor-Checks
|
||||
sind validiert; **22/22** eingeschränkte Portal-Live-Tests (P26a 14/14 + P26b 7/7 + schmaler
|
||||
Custom-Host-Resolver 1/1) belegen Customer/Subunternehmer, PortalUser/Tenant A/B, active/revoked,
|
||||
Frozen read/write und fail-closed Host-Auflösung. Zusammen mit App-/Worker- und Tenant-Bootstrap-
|
||||
Proofs ist der frische Feature-Overlay-Lauf **68/68** grün.
|
||||
|
||||
Dieser Probe-Lauf erlaubt weder `verify:migrations-parity` noch den migration-only Strict-Lauf grün
|
||||
zu markieren: Der Kandidat liegt bewusst nur außerhalb des Repositories. Vor Merge muss daraus die
|
||||
eine reviewte forward-only Migration mit Inverse-SQL entstehen; danach folgen frische Chain und
|
||||
Staging-RLS-Proof.
|
||||
|
||||
### Ausgeführter Merge-/RLS-Proof vom 2026-07-16
|
||||
|
||||
Die reviewte Migration wurde mit PR `#125` in `main` übernommen und im Deploy-Lauf
|
||||
[`#10300`](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/10300) als einmaliger
|
||||
Migrationsschritt ausgeführt. Der Lauf prüfte die exakte Revision
|
||||
`f54b04162b2823b1d2f6db0318baf1a7431c5b66`, Migration-Chain-Parität, Tenant-Policy-Vertrag,
|
||||
RLS-Release-Readiness und Live-RLS-Isolation. App, Worker und Portal liefen mit getrennten Rollen
|
||||
über PgBouncer; Core und Portal verwendeten denselben gepinnten Web-Digest und bestanden
|
||||
`/healthz`/`/readyz`. Damit sind die oben beschriebenen Merge-/RLS-Gates erfüllt.
|
||||
|
||||
## Staging-Rollout
|
||||
|
||||
1. Portal-Ressource und Core-Web zunächst ohne öffentlichen Portal-DNS vollständig
|
||||
nach der Runtime-Matrix konfigurieren. Alle Ressourcen-Allowlisten aktualisieren.
|
||||
2. Merge erst freigeben, wenn Migration, Rollen, PgBouncer und Coolify-Inventar
|
||||
vorbereitet sind.
|
||||
3. Der Main-Workflow migriert einmalig, pinnt Web und Portal auf denselben SHA/Digest,
|
||||
deployt beide getrennt und prüft `/healthz` sowie `/readyz` auf Service, Surface,
|
||||
Revision und echte DB-Rolle/RLS-Bereitschaft.
|
||||
4. Erst nach grüner interner Bereitschaft den DNS-Eintrag anlegen. Nach Estate-
|
||||
Standard bleibt Cloudflare zunächst `proxied=false`, bis das LE-Zertifikat gültig
|
||||
ist; anschließend kann `proxied=true` gesetzt werden.
|
||||
5. Die schreibenden Portal-RLS-Integrationstests laufen nur gegen eine wegwerfbare
|
||||
PostgreSQL-Instanz. Shared Staging erhält einen nicht destruktiven Rollen-/Policy-/
|
||||
Grant-/`readyz`-Proof und bewusst angelegte UAT-Fixtures.
|
||||
|
||||
## Staging-UAT
|
||||
|
||||
VA-P26b besitzt den vollständigen Admin-/Interaktionsflow; Merge-Migration und eingeschränkter
|
||||
Staging-RLS-Proof sind mit Lauf `#10300` grün. Für den formalen Handoff fehlt jetzt ein bewusst
|
||||
angelegter isolierter UAT-Tenant mit PortalUser, ProjectAccess, sichtbarer Stage, freigegebenem
|
||||
Testdokument sowie begrenztem Customer- und Subunternehmerzugang. Es werden keine
|
||||
`SEED_*`-Runtime-Schalter verwendet.
|
||||
|
||||
Zu prüfen sind mindestens:
|
||||
|
||||
- Magic-Link, optionales Passwort, Setup, Verifikation, Reset und Logout;
|
||||
- keine User-Enumeration bei unbekannter E-Mail;
|
||||
- PortalUser A/B, Tenant A/B und nicht freigegebene Projekte/Dokumente liefern 404;
|
||||
- Core-Host weist Portalpfade ab und Portalhost weist Core-/Admin-/API-/Rootpfade ab;
|
||||
- Frozen-Tenant verhält sich read-only;
|
||||
- Status-Mail enthält den richtigen Portalhost, respektiert Sichtbarkeit/Präferenz,
|
||||
wird debounced und tatsächlich zugestellt;
|
||||
- Multi-Upload/Reklamation schreibt erst nach AV-/Storage-Erfolg File-/Link-/Activity-/Inbox-
|
||||
Datensätze und benachrichtigt über `notify()`; Subunternehmer sehen weder Endkunden noch fremde
|
||||
Projekt-/Dokumentdaten;
|
||||
- Admin-Konfiguration, Rechtslink-Aktivierungsgate, Inbox-Routing, Export, 24-Stunden-Lösch-Widerruf
|
||||
und Lifecycle-Jobs verhalten sich unter Frozen read-only;
|
||||
- `/healthz` und `/readyz` melden den erwarteten Service, die erwartete Surface und
|
||||
die gebackene Revision, ohne DB-Rolle oder Secrets öffentlich auszugeben.
|
||||
|
||||
VA-P26c-UAT folgt separat erst nach echtem Billing-Provider-Proof und angelegter Controller-Ressource:
|
||||
TXT/CNAME-Verifikation, exakte Host-Auflösung, SNI/TLS-/Health-Ack, Retry/Revalidation, Remove/Switch,
|
||||
Kill-Switch und Standardhost-Fallback. Localhost-, Mock- oder manuell eingespielte Traefik-Dateien
|
||||
ersetzen diesen Proof nicht.
|
||||
|
||||
## Produktion und Rollback
|
||||
|
||||
Die VA-P26a-Grundlage darf vorab auf Staging verifiziert werden. Eine öffentliche
|
||||
Buchung beziehungsweise Produktfreischaltung erfolgt jedoch erst nach VA-P26b, wenn
|
||||
Workspace-Admin-Verwaltung, Upload/Reklamation und DSGVO-Flows vollständig verfügbar
|
||||
sind. VA-P26c schaltet danach Paket-Gates und Custom-Domains frei.
|
||||
|
||||
Produktion wird nur über den bestehenden `promote`-Workflow mit der exakt in Staging
|
||||
geprüften Live-Staging-SHA und einem erst nach Backup-Bereitschaft manuell
|
||||
gestarteten, input-freien Promote ausgerollt. Ressourcen-, Rollen-,
|
||||
PgBouncer-, Env-, DNS- und Zertifikatsvorbereitung werden vorher nochmals geprüft.
|
||||
|
||||
Vor der DB-Migration kann auf den vorherigen Web-Digest zurückgerollt und die Portal-
|
||||
Ressource beziehungsweise ihr DNS deaktiviert werden. Nach der Migration gilt der im
|
||||
Migration-File dokumentierte Inverse-SQL-Pfad; gelöschte Legacy-Zeilen benötigen das
|
||||
Backup. Core und Portal werden immer als Digest-Paar zurückgerollt, damit keine zwei
|
||||
unterschiedlichen Surface-Verträge gleichzeitig laufen.
|
||||
|
||||
Für VA-P26c bleibt der Standardhost der verpflichtende Fallback. Bei Controller-, DNS-, TLS- oder
|
||||
Entitlement-Störung wird zuerst der Domain-Kill-Switch gesetzt, die aktuelle Generation
|
||||
deprovisioniert und ausschließlich die exakt zu diesem Claim gehörende generierte Traefik-Datei
|
||||
entfernt. Danach wird die Controller-Ressource auf den zuvor geprüften immutable Digest zurückgesetzt
|
||||
oder gestoppt; Core-/Portal-Digests und fremde Host-Dateien bleiben unberührt. Die 30-Tage-Reclaim-
|
||||
Sperre wird durch einen Rollback nicht umgangen. Ohne erfolgreiches Deprovisioning-/Fallback-UAT
|
||||
wird kein Custom-Host öffentlich aktiviert.
|
||||
|
||||
## Folge-Tickets
|
||||
|
||||
- VA-P26b ergänzt Admin-Einladungen, Access-Matrix, Stage-/Dokumentfreigaben,
|
||||
Upload/Reklamation und DSGVO-Flows.
|
||||
- VA-P26c ergänzt Paket-Gates und den Self-Service-Custom-Domain-Flow inklusive
|
||||
DNS-Verifikation, Zertifikatsstatus und Deaktivierung.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user