nexus/phases/deployment.md

Deployment

Letzte Aktualisierung: 2026-06-21 Status: ✅ CD v3 (Auto + Manual) + Owner-Passwort-Persistenz (SeedAudit) Live-URL: https://nexus.noveria.net

CD-Philosophie (v3)

• CI läuft automatisch bei jedem Push → darf nie brechen
• CD auto + manuell: Automaticher Deploy nach CI-Success auf main (patch default), manueller Deploy mit voller Kontrolle via workflow_dispatch
• Loop-Schutz: Version-Bump-Commits enthalten [skip ci] — kein Re-Trigger der CI, kein Infinite-Loop
• Main-Deploys duerfen VERSION bumpen und einen Git-Tag setzen
• Nicht-Main-Deploys (anderer git_ref) deployen read-only und mutieren Git nicht
• Rollback als eigener Workflow, manuell triggerbar
• Database-Backup als eigener Workflow, manuell triggerbar (optionaler Nightly-Schedule)

Workflows

Deploy (.gitea/workflows/deploy.yaml)

Trigger:

• Automatisch: Nach erfolgreicher CI (workflow_run auf CI - Build & Test) → Default-Parameter: patch bump, all services, main ref
• Manuell: Via Gitea Actions → workflow_dispatch

Loop-Schutz:

• Version-Bump-Commits enthalten [skip ci] → Gitea startet keine neue CI
• Auto-Deploy prüft zusätzlich github.event.workflow_run.head_commit.message auf [skip ci]
• Beide Mechanismen zusammen verhindern Endlosschleife: CI → Deploy → Bump → CI …

Inputs (nur bei workflow_dispatch):

Input	Typ	Default	Beschreibung
version_bump	choice (patch/minor/major)	patch	Version-Bump-Typ
service	string	(all)	Einzelner Service oder alle
no_cache	boolean	false	Docker-Build-Cache deaktivieren
git_ref	string	main	Branch/Tag/Commit zum Deployen

Ablauf:

1. Job-Level-Guard: Auto-Deploys fuer [skip ci]-Commits werden gar nicht gestartet
2. Checkout des gewählten Git-Refs
3. Wenn git_ref = main: Version-Bump + Git-Tag + Push
4. Wenn git_ref != main: VERSION nur lesen, kein Push, kein Tag
5. Safe Secret Handling: .env wird aus Secret-Umgebungsvariablen in /tmp/nexus-deploy-env geschrieben (mode 600), NICHT im Workspace
6. Code-Sync zum Host-Deploy-Pfad
7. docker compose build && up -d --wait --force-recreate
8. .env-Tempfile wird mit shred gelöscht
9. Health-Check (exponentieller Backoff, 6 Versuche)
10. Smoke-Test (/dashboard, /health, /api/v1/operations/snapshot erwartet 401)
11. Bei Fehler: Reviewer-Handoff-Meldung mit Job-URL

Backup (.gitea/workflows/backup.yaml)

Trigger: Manuell via Gitea Actions → workflow_dispatch (optional: Nightly-Schedule via Cron)

Inputs:

Input	Typ	Default	Beschreibung
keep_on_host	boolean	false	Backup auch auf Host-Pfad kopieren
host_backup_path	string	/opt/openclaw/backups	Host-Zielpfad

Ablauf:

1. Backup-ID generieren (Timestamp-basiert)
2. docker exec nexus-postgres-1 pg_dumpall -U nexus → gzip
3. Upload als Gitea-Artifact (90 Tage Retention, bereits komprimiert)
4. Optional: Kopie auf Host-Pfad via Docker-Volume-Mount
5. Integritäts-Check: gzip-Test + SQL-Header-Validierung
6. Backup-Summary mit Restore-Befehl

Restore (manuell auf dem Host):

# Aus Gitea-Artifact herunterladen oder von Host-Pfad:
zcat nexus-backup-YYYY-MM-DDTHHMMSSZ.sql.gz | docker exec -i nexus-postgres-1 psql -U nexus -d postgres
# Danach Stack neu starten:
cd /opt/openclaw/data/openclaw/workspace/nexus
docker compose up -d --wait

Nightly-Schedule aktivieren: In backup.yaml die Zeilen auskommentieren:

schedule:
  - cron: '0 3 * * *'  # Jede Nacht um 03:00 UTC

Rollback (.gitea/workflows/rollback.yaml)

Trigger: Manuell via Gitea Actions → workflow_dispatch

Inputs:

Input	Typ	Beschreibung
target_tag	string	Git-Tag zum Zurückrollen (z.B. v0.2.49)
confirm	string	Muss exakt ROLLBACK sein (Safety-Gate)

Ablauf:

1. Safety-Gate: Bestätigungstext muss ROLLBACK sein
2. Checkout des Target-Tags
3. Tag-Validierung (existiert? welcher Commit?)
4. Safe Secret Handling (gleiches Tempfile-Pattern)
5. Code-Sync des alten Stands zum Host
6. docker compose build --no-cache && up -d --wait --force-recreate
7. Health-Check + Smoke-Test (/dashboard, /health, /api/v1/operations/snapshot erwartet 401)
8. Bei Fehler: Reviewer-Handoff mit manueller Rollback-Anleitung

DB-Migration bei Rollback: Die API führt MigrateAsync beim Start aus. Wenn die Migrationen des Rollback-Tags ein Prefix der aktuellen DB sind (Normalfall), läuft EF Core sie als No-Op. Wenn ein Rollback-Tag vor einer destruktiven Migration liegt, ist manuelles DB-Intervention nötig — ein Edge Case, der DevOps signalisiert wird.

Secrets und Konfiguration

Owner Password Persistence (2026-06-21, permanent fix)

Root Cause: Dual-Source-Architektur fuer das Owner-Passwort (Gitea-Secret ENV_OWNER_PASSWORD vs Host .env OWNER_PASSWORD) verursachte Drift wenn die DB jemals neu geseedet wurde.

Fix (3 Schichten):

1. SeedAudit-Entity (DB-Migration 20260621081500_AddSeedAudit): EnsureDatabaseAsync prueft die SeedAudit-Tabelle auf Key owner_created VOR dem Seeden. Ist dieser Key vorhanden, wird der Owner NIE neu erstellt — selbst wenn die Users-Tabelle komplett geloescht wird.
2. Single Source of Truth: Deploy- und Rollback-Workflows lesen OWNER_PASSWORD jetzt aus dem persistenten Host-.env (via grep auf dem Deploy-Pfad), NICHT mehr aus separatem Gitea-Secret. Das Host-.env ist die kanonische Quelle.
3. admin-reset-password Endpoint existiert als Recovery-Pfad (braucht Admin__ResetToken aus dem .env).

Verifikation (2026-06-21):

• Login funktioniert nach docker compose down && up (kompletter Stack-Neustart)
• Login funktioniert nach docker compose up -d --force-recreate --wait
• Login funktioniert nach docker compose restart
• SeedAudit-Eintrag owner_created blockiert erneutes Seeden bei jedem Startup

Regel gegen Wiederholung: OWNER_PASSWORD nur im Host-.env aendern. Das Host-.env wird von CI-Deploys gelesen. Niemals ein separates Gitea-Secret fuer OWNER_PASSWORD anlegen.

Secrets in Gitea

Folgende Secrets sind in Gitea (Repo → Settings → Actions → Secrets) konfiguriert:

Secret	Verwendung
ENV_POSTGRES_PASSWORD	PostgreSQL-Passwort
ENV_JWT_KEY	JWT-Signing-Key (min. 32 Bytes)
ENV_OPENCLAW_TOKEN	OpenClaw Gateway Token

Hinweis: ENV_OWNER_PASSWORD wurde aus den Gitea-Secrets ENTFERNT (2026-06-21). OWNER_PASSWORD kommt ausschliesslich aus dem Host-.env auf dem Deploy-Pfad.

Safe Secret Handling (v3)

Vorher (unsicher): Secrets wurden via ${{ secrets.X }} direkt in eine Datei im Workspace interpoliert, die dann zum Host synct wurde. Das .env lag potenziell lesbar im Workspace und auf dem Host-Dateisystem.

Jetzt (sicher):

1. Secrets werden als Step-Environment aus Gitea Secrets bezogen und erst dann in /tmp/nexus-deploy-env (mode 600) geschrieben
2. Die Temp-Datei wird via docker run -v als read-only ins Compose-Environment gemountet
3. Nach Deploy/Rollback wird die Datei mit shred -u gelöscht
4. Das .env erscheint nie im Workspace oder auf dem Host-Deploy-Pfad

Build-Anleitung (lokal oder in CI)

Die folgenden Befehle sind auf dem Build-System auszuführen. Vor dem Build müssen die Secrets in .env gesetzt sein.

# 1. Backend veröffentlichen
cd backend
dotnet publish -c Release -o dist

# 2. Frontend bauen (pnpm preferred)
cd ../frontend
pnpm install
pnpm build
# └─ Output: frontend/dist/ (statisch auslieferbar)

# 3. Docker-Stack starten (wenn compose verwendet wird)
cd ..
docker compose up -d --build

Die Container holen sich ihre Umgebungsvariablen aus der .env im Projektstamm.
Stelle sicher, dass .env existiert und alle ***-Platzhalter ersetzt sind.

Deployment-Plan

1. .env-Datei auf dem VPS anlegen (alle Secrets generieren/setzen)
2. Backup vor produktiven Infrastrukturarbeiten
3. Docker-Stack auf dem VPS deployen
4. Datenbankmigration läuft automatisch beim Start (via MigrateAsync)
5. Nginx Proxy Manager und nexus.noveria.net verbinden
6. HTTPS, Header, Cookies und externe Erreichbarkeit validieren

Abgeschlossene Deployment-Arbeit

• Produktions-.env mit starken, getrennten Secrets angelegt (2026-06-08)
• Datenbankmigration und kompletter Stack per Docker-Compose deployt
• Nexus auf dem VPS deployt (Docker Compose)
• Nginx mit Let's Encrypt SSL fuer nexus.noveria.net konfiguriert
• HTTPS, Security-Header (HSTS, X-Content-Type-Options, X-Frame-Options), Cookies validiert
• Externe Erreichbarkeit bestaetigt (2026-06-09)
• CI/CD entkoppelt — Deploy darf automatisch (v3) oder manuell (2026-06-13)
• Automatischer Deploy nach CI-Success auf main mit Loop-Schutz via [skip ci] (2026-06-13)
• Safe Secret Handling: Tempfile in /tmp statt Workspace-Datei (2026-06-13)
• Rollback-Workflow implementiert mit Safety-Gate (2026-06-13)
• Main-Deploys koennen Version-Bump + Git-Tag automatisch setzen; Non-Main-Deploys bleiben read-only (2026-06-13)
• Reviewer-Handoff bei Deploy/Rollback-Fehlern (2026-06-13)
• Database-Backup-Workflow mit pg_dumpall + Gitea-Artifact (2026-06-13)
• Live-Recheck nach Deploy-Stoerung: /health, SPA-Root und GET /api/dashboard/tasks wieder 200; Bao-Folgetask zur Agent-Progress-Visibility erstellt (2026-06-20)
• Agent-Progress-Stand (2d21885) manuell als sauberer Commit-Snapshot live ausgerollt, nachdem der normale Gitea-Deploy-Trigger blockierte (2026-06-20)

Verifizierung

2026-06-20

• https://nexus.noveria.net/ → 200 OK, SPA geladen (<title>Nexus | Noveria Operations</title>)
• /health → 200 Healthy, PostgreSQL + Runtime healthy
• /api/dashboard/tasks → 200 OK mit X-Nexus-Api-Key
• Follow-up-Task Restore agent progress visibility in Nexus fuer assignedTo=bao erfolgreich angelegt

2026-06-09

• https://nexus.noveria.net → 200 OK, SPA geladen
• /health → Healthy
• /dashboard, /login → SPA-Routing korrekt
• /api/v1/operations/snapshot → 401 Unauthorized (Auth-Schutz aktiv)
• Let's Encrypt TLS-Zertifikat aktiv
• Nginx-Proxy → 127.0.0.1:18880

Incident-Hinweis (2026-06-14)

• Verifizierter Ausfallpfad: api konnte wegen DB-Passwort-Mismatch nicht healthy werden; dadurch blieb web per depends_on: service_healthy im Status Created.
• Nach einem isolierten API-Fix startet web nicht automatisch nach. Sicherer Minimalpfad:
  1. docker compose ps
  2. curl http://127.0.0.1:18880/health
  3. Falls health=200, aber /dashboard noch nicht 200 und web auf Created steht: docker compose up -d web
  4. Danach extern /dashboard, /health und /api/v1/operations/snapshot erneut prüfen
• Der manuelle Helper ops/deploy.sh verifiziert deshalb jetzt nicht mehr nur /health, sondern auch /dashboard und den Auth-Schutz der Operations-API.

Offene Arbeit

• [!] Gitea-Deploy-Trigger reparieren: POST /actions/workflows/deploy.yaml/dispatches liefert aktuell HTTP 500; fuer Commit 2d21885 war deshalb kein erfolgreicher normaler Deploy-Run belegbar
• Docker-Socket-Risiko im CD-Workflow final adressieren (kommt spaeter)
• Docker-Logs und Container-Health-Monitoring einrichten
• Restore-Drill fuer Backup/Recovery einmal realistisch durchspielen und dokumentieren
• Direkt-Pushes auf main waehrend eines Main-Deploys organisatorisch vermeiden oder spaeter technisch haerter absichern

Deploy-Trigger-Actor (2026-06-14)

• Deploy-Trigger werden durch DevOps (nicht Iris) ausgelöst
• Git-Remote origin verwendet DevOps-Token → Gitea zeigt devops als Actor
• Workflow-Dispatch API-Calls mit DevOps-Token authentifizieren