ibo/infra/RUNBOOK-ibo.md

Runbook — ibo (Immo-Bot) containerisieren, deployen, Zitadel-SSO davorschalten

Immo-Bot = Flask-Web-App + Selenium-Chrome-Sidecar (noVNC-Live-Ansicht). Zwei feste Umgebungen (KEINE PR-Previews):

Umgebung	Host	TLS-Secret	Deploy
dev	dev.ibo.momentrum.de	ibo-dev-tls	automatisch bei jedem main-Push (CI)
prod	ibo.momentrum.de	ibo-tls	manuell promotet (Tag-Copy, s. u.)

Beide hinter demselben Zitadel-oauth2-proxy ibo-sso (cookie-domain .ibo.momentrum.de deckt dev und prod ab).

Die Muster spiegeln kanban (CI/Chart/CD) und luxly-sso/dev-sso (oauth2-proxy). Cluster-, Zitadel- und DNS-Schritte sind manuell — dieses Runbook ist die Anleitung. Reihenfolge unten einhalten.

---

0. Repo nach Gitea bringen

cd projekte/ibo
git init && git add -A && git commit -m "ibo: containerize + CI + infra"
git remote add origin momentrum-gitea:momentrum/ibo.git   # SSH-Alias wie andere Repos
git push -u origin main    # push-create legt momentrum/ibo an, falls aktiviert

Gitea-Actions-Secrets am Repo momentrum/ibo setzen (Settings → Actions → Secrets):

• REGISTRY_USER, REGISTRY_TOKEN — Push in die Gitea-Registry.
• DEPLOY_TOKEN — Gitea-Token mit Write auf momentrum/momentrum-deploy (Write-back des dev-Image-Tags).

---

1. Zitadel: Redirect-URI ergaenzen (KEIN neuer Client)

ibo-sso nutzt — wie luxly-sso — den bestehenden geteilten Zitadel-Client (K8s-Secret oauth2-proxy-dev in ns iam). Es ist kein neuer Client und kein neues Secret noetig. Nur am vorhandenen Client im Zitadel-Console (https://auth.momentrum.de) die Redirect-URI ergaenzen:

• Redirect-URI hinzufuegen: https://sso.ibo.momentrum.de/oauth2/callback

(EIN Login-Host sso.ibo.momentrum.de deckt per cookie-domain .ibo.momentrum.de dev und prod ab. Wer prod spaeter mit eigenem Blast-Radius trennen will: eigenen Client + eigenes SealedSecret anlegen und im ibo-sso-Deployment referenzieren — die oauth2-proxy-dev-Secret-Refs dort ersetzen.)

---

2. oauth2-proxy ibo-sso (contabo-infra) — deployen

Manifeste liegen in contabo-infra/platform/manifests/ibo-sso/ (Deployment/Service, Middlewares oauth2-ibo-auth/oauth2-ibo-errors, Ingress sso.ibo.momentrum.de, oauth2-Passthrough-Route). Sie referenzieren das bestehende Secret oauth2-proxy-dev + die ConfigMap oauth2-proxy-dev-templates — nichts einzusealen.

Die ArgoCD-App platform/apps/ibo-sso.yaml wird vom platform-App-of-Apps automatisch aufgenommen (gleiche Ablage wie luxly-sso.yaml) — committen & pushen genuegt; alternativ einmalig kubectl apply -f platform/manifests/ibo-sso/. Ausserdem ist das ibo-Repo in platform/manifests/argocd-projects/internal.yaml (sourceRepos) bereits ergaenzt — sonst lehnt ArgoCD die App-Source ab.

Ergebnis:

• Middlewares iam-oauth2-ibo-auth@kubernetescrd / iam-oauth2-ibo-errors@kubernetescrd stehen bereit (die App-Ingresses referenzieren sie).
• https://sso.ibo.momentrum.de liefert die Login-Seite (kein Auth davor).

---

3. DNS

A/AAAA-Records auf die Cluster-Ingress-IP zeigen lassen:

• ibo.momentrum.de
• dev.ibo.momentrum.de
• sso.ibo.momentrum.de

cert-manager (letsencrypt-prod, HTTP-01) stellt die Zertifikate ibo-tls, ibo-dev-tls, ibo-sso-tls automatisch aus, sobald DNS steht.

---

4. Deploy-Reihenfolge

1. Repo gepusht (Schritt 0) → CI baut das erste Image und bumpt apps/internal/ibo/dev.yaml (image.tag).
2. ibo-sso laeuft (Schritt 2), DNS steht (Schritt 3).
3. CD-Apps im momentrum-deploy committen: apps/internal/ibo/dev.yaml + apps/internal/ibo/app.yaml. ArgoCD legt Namespace apps-ibo an und synct.
4. Erstes Prod-Promote: den von der CI in dev.yaml gesetzten image.tag nach app.yaml kopieren (siehe unten) — sonst hat prod noch tag: latest.

---

5. Prod promoten (Routine)

Prod bekommt bewusst NUR den Tag, den man freigibt:

cd momentrum-deploy
DEVTAG=$(grep -E '^          tag: ' apps/internal/ibo/dev.yaml | awk '{print $2}')
sed -i "s|^          tag: .*|          tag: ${DEVTAG}|" apps/internal/ibo/app.yaml
git commit -am "ibo: promote ${DEVTAG} -> prod" && git push

ArgoCD synct prod auf den neuen Tag. Rollback = git revert dieses Commits.

---

6. Browser-Live-Ansicht (noVNC)

Der Automations-Chrome laeuft im selenium-Sidecar; sein Bild wird per noVNC gestreamt und in der Web-App eingebettet (Button „👁️ Browser live ansehen", oeffnet auch automatisch beim Consent-Browser). Routing:

• App-Container → Chrome via SELENIUM_REMOTE_URL=http://localhost:4444.
• Client-Browser → https://<host>/novnc/… → Ingress-Pfad /novnc → stripPrefix-Middleware → Sidecar-Port 7900 (noVNC/websockify).
• Steuerbar durch die SSO-Cookie (gleicher Host, gleiche Middlewares).

Der Browser laeuft serverseitig im Container — es wird NICHT der lokale Browser des Nutzers ferngesteuert (das ginge von einer gehosteten App aus nicht).

---

7. Break-glass (Notzugang)

Faellt Zitadel aus: die SSO-Middlewares temporaer aus ingress.ssoMiddlewares im jeweiligen CD-App-YAML entfernen (die App selbst hat keine eigene Auth → sie ist dann OFFEN). Nur kurz, danach sofort zuruecksetzen. Nie ungeschuetzt lassen.

---

8. Verifikationscheckliste

• docker compose up -d lokal → http://localhost:5000 UI, „Browser live ansehen" zeigt den Chrome im iframe (localhost:7900).
• curl -s localhost:5000/healthz → {"ok":true}.
• main-Push → CI gruen (version→test→build-push→helm-validate→deploy-dev), dev.yaml-Tag gebumpt, ArgoCD rollt dev.
• https://dev.ibo.momentrum.de → Redirect zu auth.momentrum.de, nach Login landet man in der App.
• In der App eingebettetes /novnc/ zeigt den Live-Browser.
• https://ibo.momentrum.de nach Promote ebenso hinter Zitadel.
• Ohne SSO-Session → Login-Redirect (kein rohes 401).