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

```sh
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:

```sh
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).