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

@@ -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.