nexarch/docs/ROLLOUT-131-VORBEREITUNG.md

Rollout-Vorbereitung Host 131 (Vorstufe zur Produktion)

Stand: main Head 54589a4e. Dieses Dokument bereitet den Rollout vor, führt ihn aber NICHT aus — kein Dienst wird gestartet oder neu gestartet. Das ist ausdrücklich der letzte, manuelle Schritt des Nutzers (Sicherheitsfilter blockt automatisierte Production-Deploy-Aktionen kategorisch).

Installierbare Artefakte liegen im Repo, nicht nur als Text hier:

• deploy/systemd/nexarch-connect-app.service.tmpl (neu)
• deploy/systemd/nexarch-dms-app.service.tmpl (neu — gab es bisher gar nicht im Repo, da dms-app noch nie deployt wurde)
• deploy/systemd/nexarch-dms-worker.service.tmpl (neu, gleicher Grund)
• deploy/rollout-131-sync.sh (idempotent, kein systemctl start/restart/stop) — bereits einmal real auf 131 ausgeführt (2026-09-26), Ergebnis siehe Abschnitt 2/3
• deploy/rollout-131-healthcheck.sh (neu) — nach dem manuellen Dienststart auszuführen, prüft alle relevanten Ports per curl, startet selbst nichts

1. Was auf 131 aktuell läuft

Geprüft per systemctl list-units und Prozessliste (2026-09-25):

Aktiv und laufend (unverändert lassen, sofern nicht unten als "Neustart nötig" markiert):

• nexarch-core, nexarch-account-api, nexarch-kek-api, nexarch-notify-api, nexarch-notifyprefs-api, nexarch-policy-api, nexarch-rbac-admin-api, nexarch-resync-api (Core)
• nexarch-archive-moduleadapter-api, nexarch-archive-retention-api, nexarch-archive-restoretest-metrics, nexarch-archive-scrub-metrics (Archive)
• nexarch-dms-kosit (DMS KoSIT-Validator, Loopback-Sidecar, MET-07-Vorbedingung)
• Sechs Devserver: nexarch-auditlog-devserver, nexarch-licadmin-devserver, nexarch-metrics-devserver, nexarch-secheaders-devserver, nexarch-statuspage-devserver, nexarch-tenantadmin-devserver
• Sechs Web-Frontends (next-server-Prozesse): nexarch-web-account, nexarch-web-audit-log, nexarch-web-lic-admin, nexarch-web-notifications, nexarch-web-rbac-admin, nexarch-web-status-page, nexarch-web-tenant-admin

Bereits fehlgeschlagen, unabhängig von diesem Rollout (nicht Teil dieses Auftrags, nur dokumentiert):

• nexarch-archive-backup-full, nexarch-archive-backup-incremental, nexarch-archive-objectbackup-rotate, nexarch-archive-reconcile, nexarch-archive-scrub — Status failed. Ursache nicht untersucht (außerhalb des Auftrags), sollte vor dem eigentlichen Rollout separat geprüft werden.

Nicht vorhanden auf 131 (bisher nirgends deployed):

• dms-app selbst (nur der KoSIT-Sidecar läuft, nicht der eigentliche DMS-Dienst) — trotz dms-app.env vorhanden
• Mail (kein mail-api/mail-rules-api-Dienst, keine Env-Datei)
• AI, Workflow, Connect — komplett neu für 131

2. Build-Ergebnis (real ausgeführt, 2026-09-26)

deploy/rollout-131-sync.sh wurde tatsächlich auf 131 ausgeführt (Code vorher per rsync -az --delete --exclude='.git' synchronisiert). Ergebnis: alle sieben Module bauen sauber (go build ./... + go vet ./..., exit 0) — Core, dms, archive, mail, ai, workflow, connect. Kompilierfehler wären hier aufgefallen, es gab keine.

Wichtig: AI und Workflow haben (Stand main Head 54589a4e) keinen eigenen cmd/-Dienst — reine Bibliotheks-Module. Für sie gibt es nichts zu installieren/starten. Kein Unit-Template dafür angelegt (wäre eine Attrappe für ein nicht existierendes Binary).

3. Neue Umgebungsvariablen je Dienst

Connect (connect-app, neuer Dienst)

/etc/nexarch/connect-app.env wurde angelegt. Verbleibende echte TODOs (2 von 2) — beides Werte, die nur der Nutzer festlegen kann (Portwahl bzw. Ziel-Datenbank), nicht automatisch ableitbar:

Variable	Status	Zweck
NEXARCH_CONNECT_APP_LISTEN_ADDR	TODO	Horch-Adresse, z. B. 127.0.0.1:9500
NEXARCH_CONNECT_APP_TENANT_DSN	TODO	Postgres-DSN für den Connect-Mandanten

DMS (dms-app, noch nicht auf 131 installiert — dieser Rollout würde ihn erstmals aufsetzen)

/etc/nexarch/dms-app.env hatte 12 der ~86 in dms/docs/BETRIEB-UMGEBUNGSVARIABLEN.md dokumentierten Variablen gesetzt. Beim realen Lauf von rollout-131-sync.sh (2026-09-26) wurden die für den Start kritischen fehlenden Variablen ergänzt — 6 davon automatisch mit einem echten, für 131 zutreffenden Wert befüllt (reine URLs/Pfade, keine Geheimnisse, oder lokal generierte Secrets, oder von einem anderen bereits laufenden Dienst auf 131 abgeschrieben ohne den Wert je auszugeben):

Variable	Status	Wert/Herkunft
NEXARCH_DMS_APP_CORE_JWKS_URL	gesetzt	http://127.0.0.1:8099/auth/module-jwks — Achtung: account-api lief zum Zeitpunkt der Vorbereitung noch auf einem Stand vor F-07, Route antwortete 404. Der Code auf 131 wurde durch rollout-131-sync.sh bereits neu gebaut; ein systemctl restart nexarch-account-api (durch den Nutzer) sollte die Route freischalten — vor dem dms-app-Start mit curl erneut prüfen
NEXARCH_DMS_APP_STAGING_DIR	gesetzt	/var/lib/nexarch-dms/staging (angelegt)
NEXARCH_DMS_APP_DOWNLOAD_SIGNING_SECRET	gesetzt	lokal mit openssl rand -hex 32 generiert (rein intern, kein Abgleich nötig)
NEXARCH_DMS_APP_CORE_BASE_URL	gesetzt	http://127.0.0.1:8080 (nexarch-core auf 131)
NEXARCH_DMS_APP_POLICY_URL	gesetzt	http://127.0.0.1:8093 (policy-api auf 131)
NEXARCH_DMS_APP_KEK_ENDPOINT_URL	gesetzt	http://127.0.0.1:8102 (kek-api auf 131)
NEXARCH_DMS_APP_POLICY_SERVICE_TOKEN	gesetzt	vom bereits laufenden policy-api.env (NEXARCH_POLICY_SERVICE_TOKEN) 1:1 übernommen, Wert nie ausgegeben

Verbleibende echte TODOs (3):

Variable	Zweck
NEXARCH_DMS_APP_CORE_SERVICE_TOKEN	Tenant-Bestätigung gegen Core-Registry (INT-14) — braucht einen auf Core-Seite hinterlegten, passenden Wert; nicht ohne Core-seitige Gegenstelle generierbar
NEXARCH_DMS_APP_KEK_CLIENT_ID / _CLIENT_SECRET	KEK-Bezug — laut bestehender Doku auf 131 "derzeit nicht gesetzt"; braucht eine echte Registrierung bei kek-api, kann nicht geraten werden

AI, Workflow, Mail

Kein cmd/-Dienst (AI/Workflow) bzw. kein bisher deployter Dienst (Mail) — keine Env-Datei nötig für diesen Rollout-Schritt. Sobald AI/Workflow einen eigenen Dienst bekommen (kein Ticket dafür bisher vorhanden), braucht dieses Dokument eine Ergänzung.

4. Neustart-Bedarf bestehender Dienste

Kein bereits laufender Dienst MUSS für die reine Installation von Connect neu gestartet werden — Connect ist ein komplett neuer, unabhängiger Prozess. Ein Neustart von nexarch-core/nexarch-policy-api/etc. ist nur nötig, wenn deren EIGENE Env-Dateien geändert werden — das tut rollout-131-sync.sh nicht (nur connect-app.env und dms-app.env werden ergänzt, beide betreffen keinen aktuell laufenden Dienst).

5. Manuelle Schritte für den Nutzer (der eigentliche Rollout)

Schritte 1–2 wurden bereits real ausgeführt (siehe Abschnitt 2/3) und müssen nur wiederholt werden, falls sich main-Head seither geändert hat.

Primärer Weg: die restlichen Schritte (3–9 unten) sind jetzt in deploy/rollout-131-apply.sh automatisiert. Nachdem die 5 TODO-Werte eingetragen sind, genügt:

sudo ./deploy/rollout-131-apply.sh

Das Skript bricht kontrolliert ab, wenn ein TODO-Wert noch fehlt, wenn der Build fehlschlägt, oder wenn account-api nach dem Neustart /auth/module-jwks nicht innerhalb von 20s liefert — es macht in keinem dieser Fälle blind weiter. Es ruft systemctl restart/enable --now nur für die in diesem Rollout betroffenen Dienste auf (nexarch-account-api, nexarch-connect-app, nexarch-dms-app, nexarch-dms-worker), keine anderen. Am Ende führt es automatisch rollout-131-healthcheck.sh aus.

Einzelschritte als Referenz/Fallback, falls das Skript nicht genutzt werden soll oder ein Einzelschritt manuell wiederholt werden muss:

1. Code synchronisieren (erledigt, rsync von der Entwicklungsmaschine gegen main Head 54589a4e)
2. ./deploy/rollout-131-sync.sh ausführen (erledigt, alle 7 Module bauen sauber, Env-Dateien ergänzt)
3. Die 5 verbleibenden echten # TODO-Werte von Hand eintragen (Abschnitt 3 nennt sie einzeln): NEXARCH_CONNECT_APP_LISTEN_ADDR, NEXARCH_CONNECT_APP_TENANT_DSN, NEXARCH_DMS_APP_CORE_SERVICE_TOKEN, NEXARCH_DMS_APP_KEK_CLIENT_ID, NEXARCH_DMS_APP_KEK_CLIENT_SECRET
4. Binaries an ihren Zielort kopieren (Muster wie bei bestehenden Diensten, z. B. /opt/nexarch-connect/bin/connect-app, /opt/nexarch-dms/bin/dms-app, /opt/nexarch-dms/bin/dms-worker) und die drei neuen .service.tmpl-Dateien (nexarch-connect-app, nexarch-dms-app, nexarch-dms-worker) nach /etc/systemd/system/ kopieren, dabei __INSTALL_DIR__ (und bei DMS zusätzlich __STORAGE_DIR__/__STAGING_DIR__) durch die echten Pfade ersetzen
5. Für dms-worker fehlt noch eine eigene /etc/nexarch/dms-worker.env (siehe dms/docs/BETRIEB-UMGEBUNGSVARIABLEN.md, Abschnitt "dms-worker") — bisher nicht angelegt, da dieser Rollout sich auf dms-app konzentriert hat; ohne sie verarbeitet kein Worker die Jobqueue
6. systemctl daemon-reload
7. nexarch-account-api neu starten (Code wurde bereits neu gebaut, Route /auth/module-jwks fehlt im aktuell laufenden Prozess noch — siehe Abschnitt 3), danach mit curl http://127.0.0.1:8099/auth/module-jwks verifizieren
8. systemctl enable --now nexarch-connect-app nexarch-dms-app (und nexarch-dms-worker, sobald Schritt 5 erledigt ist)
9. ./deploy/rollout-131-healthcheck.sh ausführen (neu, liest nur, startet nichts) — zeigt kompakt welcher Dienst erreichbar ist
10. Bei Bedarf weitere, bereits laufende Dienste neu starten, falls deren eigene Env-Dateien geändert wurden (aktuell: nur nexarch-account-api, siehe Schritt 7 — kein anderer Dienst betroffen)

Die fünf bereits fehlgeschlagenen Backup-/Scrub-/Reconcile-Dienste (Abschnitt 1) sind unabhängig von diesem Rollout und sollten separat untersucht werden.

6. Mail, Workflow, AI (2026-09-26, Nachtrag)

Auf 131 vorbereitet: Code frisch synchronisiert (main Head c3c9034), alle drei Module bauen sauber (go build ./... + go vet ./..., exit 0, kein Kompilierfehler).

Echter, ehrlicher Fund — kein Dienst installierbar: Keines der drei Module hat einen echten, zusammenfassenden cmd/-Diensteinstiegspunkt, der einen Port öffnet:

• Mail: mail/cmd/ enthält nur mailsearch-a11y-fixture (Test-Fixture für Browser-Checks) und pflichttestgate (CI-Gate-CLI) — kein cmd/mail-api/cmd/mail-rules-api. Die HTTP-API-Handler (mailapi, mailrulesapi) existieren als Bibliothekspakete, aber niemand registriert sie auf einem Mux mit ListenAndServe.
• Workflow: workflow/cmd/ existiert nicht einmal. Alle API-Layer dieser Session (approvalapi, backchannelapi, caseoverviewapi, routingruleapi) sind reine Bibliothekspakete.
• AI: ai/cmd/ enthält nur extractapi-a11y-fixture, summaryapi-a11y-fixture, pflichttestgate — dieselbe Lücke wie Mail. summaryapi, semanticsearchapi, extractapi sind Bibliothekspakete ohne bündelnden Dienst.

Keine Env-Datei, kein systemd-Unit-Template für diese drei Module angelegt — wäre eine Attrappe für ein nicht existierendes Binary (gleiches Prinzip wie beim ursprünglichen DMS/AI/Workflow-Fund vom 2026-09-25).

Empfehlung: Vor einem echten 131-Rollout für Mail/Workflow/AI braucht jedes Modul zuerst einen eigenen cmd/<modul>-app/main.go, der die bestehenden API-Handler-Pakete auf einem gemeinsamen http.ServeMux registriert und über httpharden/das etablierte Muster (siehe dms/cmd/app, connect/cmd/connect-app) einen Port öffnet. Das ist kein reiner Rollout-Schritt mehr, sondern echte Entwicklungsarbeit — sollte als eigenes Ticket je Modul angelegt werden (z. B. „ENG-08 – Erster laufender Dienst“ analog zu Connects API-02), nicht als Teil dieser Rollout-Vorbereitung improvisiert.