chore: wip on demo-gymburgdorf inventory and architecture notes

ARCHITECTURE.md

@@ -0,0 +1,207 @@
+<!-- markdownlint-disable MD013 MD060 -->
+# Architekturskizze — `demo-gymburgdorf`
+
+Diese Skizze zeigt, wie das `reference-ansible`-Repo am Beispiel der
+Inventory `demo-gymburgdorf` funktioniert: welche Hosts existieren,
+welche Rollen darauf laufen, wo welche Variablen hingehören und wie
+Secrets aus OpenBao gelookupt werden.
+
+## 1. Variablen-Hierarchie (Ansible Precedence)
+
+```mermaid
+flowchart TB
+    classDef rolelayer fill:#fef3c7,stroke:#92400e,color:#000
+    classDef grouplayer fill:#dbeafe,stroke:#1e40af,color:#000
+    classDef hostlayer fill:#dcfce7,stroke:#166534,color:#000
+    classDef vaultlayer fill:#fee2e2,stroke:#991b1b,color:#000
+
+    R["<b>role defaults/main.yml</b><br/>(niedrigste Precedence)<br/>~180 Variablen über 12 Rollen<br/>z.B. traefik_use_ssl: false<br/>keycloak_admin_password: changeme"]:::rolelayer
+
+    GA["<b>group_vars/all/</b><br/>docker.yml → docker_registry_mirrors<br/>vault.yml → vault_addr, vault_mount"]:::grouplayer
+
+    GT["<b>group_vars/traefik_servers/</b><br/>traefik.yml<br/>traefik_use_ssl, traefik_cert_mode: acme<br/>traefik_acme_dns_zone<br/>traefik_acme_tsig_* (Vault-Lookup!)"]:::grouplayer
+
+    GB["<b>group_vars/backend_servers/</b><br/>traefik.yml → traefik_mode: backend"]:::grouplayer
+
+    HR["<b>host_vars/reverseproxy/</b><br/>traefik.yml → traefik_mode: dmz"]:::hostlayer
+
+    HA["<b>host_vars/application/</b> (fehlt aktuell!)<br/>FQDNs, OIDC-Clients, DB-Passwords<br/>nextcloud_domain, authentik_domain, ..."]:::hostlayer
+
+    HS["<b>host_vars/storage/</b> (fehlt aktuell!)<br/>garage_s3_domain, garage_*_token<br/>traefik_dmz_exposed_services (für DMZ)"]:::hostlayer
+
+    V["<b>HashiCorp Vault / OpenBao</b><br/>bao.digitalboard.ch<br/>mount: demo-gymburgdorf<br/>z.B. demo-gymburgdorf/data/acme-tsig"]:::vaultlayer
+
+    R --> GA --> GT --> GB --> HR
+    GB --> HA
+    GB --> HS
+    GT -.Lookup zur Laufzeit.-> V
+    HA -.Lookup zur Laufzeit.-> V
+    HS -.Lookup zur Laufzeit.-> V
+```
+
+Höhere Ebene überschreibt tiefere. `host_vars/reverseproxy/traefik_mode: dmz`
+schlägt also `group_vars/backend_servers/traefik_mode: backend` —
+möglich, weil `reverseproxy` *nicht* in `backend_servers` ist.
+
+## 2. Inventory-Topologie demo-gymburgdorf
+
+```mermaid
+flowchart LR
+    classDef dmz fill:#fee2e2,stroke:#991b1b,color:#000
+    classDef app fill:#dcfce7,stroke:#166534,color:#000
+    classDef stor fill:#dbeafe,stroke:#1e40af,color:#000
+    classDef turn fill:#fef9c3,stroke:#854d0e,color:#000
+
+    subgraph ALL["group: all_servers (alle Hosts)"]
+        direction LR
+        subgraph DMZ["DMZ-Segment 172.16.9.0/24"]
+            RP["<b>reverseproxy</b><br/>172.16.9.111<br/>traefik_mode: dmz"]:::dmz
+            TURN["<b>turn</b><br/>172.16.9.112<br/>(STUN/TURN)"]:::turn
+        end
+        subgraph BE["Backend-Segment 172.16.19.0/24<br/>(group: backend_servers)"]
+            APP["<b>application</b><br/>172.16.19.101<br/>traefik_mode: backend<br/>+ nextcloud, opencloud,<br/>collabora, drawio,<br/>authentik, authentik_outpost_ldap"]:::app
+            ST["<b>storage</b><br/>172.16.19.102<br/>traefik_mode: backend<br/>+ garage (S3)"]:::stor
+        end
+    end
+
+    RP -.HTTP/HTTPS reverse proxy.-> APP
+    RP -.HTTP/HTTPS reverse proxy.-> ST
+```
+
+Gruppen-Mitgliedschaften (`hosts.yml`):
+
+- `traefik_servers` ⊇ `all_servers` → **alle 4 Hosts** bekommen Traefik
+  (DMZ-Modus für `reverseproxy`, Backend-Modus für `application`/`storage`).
+- `backend_servers = {application, storage}` → setzt
+  `traefik_mode: backend` via group_vars.
+- Service-Gruppen (`nextcloud_servers`, `garage_servers`, …) sind
+  Single-Host-Wrapper, mit denen `playbooks/site.yml` gezielt
+  deploybare Rollen targetet.
+
+## 3. Service-Layout & Variablen-Verortung
+
+```mermaid
+flowchart TB
+    classDef rp fill:#fee2e2,stroke:#991b1b,color:#000
+    classDef ap fill:#dcfce7,stroke:#166534,color:#000
+    classDef st fill:#dbeafe,stroke:#1e40af,color:#000
+    classDef ext fill:#e9d5ff,stroke:#6b21a8,color:#000
+
+    Internet((Internet))
+    DNS["DNS ns1.digitalboard.ch<br/>RFC2136 TSIG (key: acme_update_key_demo_gymb)<br/>dynamic zone: demo-gymb._acme.digitalboard.ch<br/>CNAME-bridge: _acme-challenge.*.gymb.souveredu.ch"]:::ext
+    BAO["OpenBao<br/>bao.digitalboard.ch<br/>mount: demo-gymburgdorf"]:::ext
+
+    subgraph RP["<b>reverseproxy</b> — traefik dmz"]
+        TRDMZ["traefik (file provider)<br/>📍 group_vars/traefik_servers/traefik.yml<br/>  → acme, tsig, ssl<br/>📍 host_vars/reverseproxy/traefik.yml<br/>  → traefik_mode: dmz<br/>📍 host_vars/reverseproxy/...<br/>  → traefik_dmz_exposed_services"]:::rp
+    end
+
+    subgraph APP["<b>application</b> — backend"]
+        TRA["traefik (docker provider)<br/>📍 group_vars/backend_servers<br/>  → traefik_mode: backend"]:::ap
+        NC["nextcloud<br/>📍 host_vars/application/nextcloud.yml<br/>  domain, postgres_pw, oidc, s3, ldap"]:::ap
+        OC["opencloud<br/>📍 host_vars/application/opencloud.yml<br/>  oidc_issuer, ldap, s3"]:::ap
+        AK["authentik<br/>📍 host_vars/application/authentik.yml<br/>  secret_key, postgres, ldap_apps, oidc_apps"]:::ap
+        AKO["authentik_outpost_ldap<br/>📍 host_vars/application/authentik_outpost_ldap.yml<br/>  host, token"]:::ap
+        COL["collabora<br/>📍 host_vars/application/collabora.yml<br/>  domain, allowed_domains"]:::ap
+        DRW["drawio<br/>📍 host_vars/application/drawio.yml"]:::ap
+    end
+
+    subgraph ST["<b>storage</b> — backend"]
+        TRS["traefik (docker provider)"]:::st
+        GAR["garage (S3)<br/>📍 host_vars/storage/garage.yml<br/>  s3_domain, rpc_secret,<br/>  admin_token, s3_keys"]:::st
+    end
+
+    Internet -->|HTTPS :443| TRDMZ
+    TRDMZ -->|HTTP backend| TRA
+    TRDMZ -->|HTTP backend| TRS
+    TRA --> NC & OC & AK & COL & DRW & AKO
+    TRS --> GAR
+
+    NC -. S3 .-> GAR
+    OC -. S3 .-> GAR
+    NC -. OIDC .-> AK
+    OC -. OIDC .-> AK
+    NC -. WOPI .-> COL
+    OC -. WOPI .-> COL
+    NC -. LDAP .-> AKO
+    OC -. LDAP .-> AKO
+    AKO -. RPC + token .-> AK
+
+    TRDMZ -. ACME DNS-01 TSIG .-> DNS
+    TRDMZ -. lookup acme-tsig .-> BAO
+    AK -. lookup secrets .-> BAO
+    NC -. lookup secrets .-> BAO
+    GAR -. lookup secrets .-> BAO
+```
+
+## 4. Deploy-Flow
+
+```mermaid
+sequenceDiagram
+    participant U as User (make)
+    participant M as Makefile
+    participant A as ansible-playbook
+    participant V as OpenBao
+    participant H as Hosts
+
+    U->>M: make bao
+    M->>V: bao login (OIDC)
+    V-->>M: VAULT_TOKEN
+    U->>M: make deploy_site_demo_gymburgdorf
+    M->>A: ansible-playbook site.yml -i inventories/demo-gymburgdorf/hosts.yml
+    A->>A: lade group_vars/all → group_vars/traefik_servers → group_vars/backend_servers → host_vars/*
+    A->>V: community.hashi_vault Lookups (acme-tsig, secrets)
+    V-->>A: secret values
+    A->>H: Play "base" → all_servers
+    A->>H: Play "traefik" → traefik_servers (dmz auf reverseproxy, backend auf application/storage)
+    A->>H: Play "garage" → storage
+    A->>H: Play "authentik / nextcloud / collabora / ..." → application
+```
+
+## 5. Variablen-Cheatsheet — wo gehört was hin?
+
+| Variable | Wohin in `demo-gymburgdorf/` | Warum |
+|---|---|---|
+| `vault_addr`, `vault_mount` | `group_vars/all/vault.yml` ✅ | Vault-Endpoint gilt site-weit |
+| `docker_registry_mirrors` | `group_vars/all/docker.yml` ✅ | Pulls aus Mirror auf allen Hosts |
+| `traefik_acme_*`, `traefik_use_ssl`, `traefik_cert_mode` | `group_vars/traefik_servers/traefik.yml` ✅ | Gilt für alle Traefik-Instanzen (dmz + backend) |
+| `traefik_mode: backend` | `group_vars/backend_servers/traefik.yml` ✅ | Default für app + storage |
+| `traefik_mode: dmz` | `host_vars/reverseproxy/traefik.yml` ✅ | Host-spezifischer Override |
+| `traefik_dmz_exposed_services` | **`host_vars/reverseproxy/`** | Liste, welche Backend-Services die DMZ proxyt (nur dort sinnvoll) |
+| `nextcloud_*`, `authentik_*`, `opencloud_*`, `collabora_*`, `drawio_*` | **`host_vars/application/<service>.yml`** | Service läuft genau auf `application` |
+| `garage_*` | **`host_vars/storage/garage.yml`** | Service läuft genau auf `storage` |
+| Secrets (Passwords, Tokens, Keys) | Inline-Variable mit `lookup('community.hashi_vault.hashi_vault', vault_mount + '/data/<path>', url=vault_addr)` | Single source of truth; Pattern wie bei `_acme_tsig` |
+
+## 6. Traefik-Modi (zentral für die Architektur)
+
+**`traefik_mode: dmz`** (Public-facing Reverse Proxy auf `reverseproxy`):
+
+- Aggregiert Services von Backend-Servern via
+  `traefik_dmz_exposed_services` (Host-Variablen).
+- Nutzt **file provider** mit `services.yml` für statisches Routing.
+- Kein Docker-Socket gemountet — keine lokalen Container.
+- Routet zu `backend_host` auf anderen Maschinen.
+- Selektive Backend-Auswahl via `traefik_backend_servers_to_proxy`.
+
+**`traefik_mode: backend`** (Application/Storage Server):
+
+- Mountet Docker-Socket (`/var/run/docker.sock`).
+- Nutzt **docker provider** für Auto-Discovery lokaler Container.
+- Services mit Label `traefik.enable=true` werden automatisch exponiert.
+- Beide Modi unterstützen ACME (RFC2136 DNS Challenge) oder Self-Signed.
+
+## 7. Was im aktuellen `demo-gymburgdorf` noch fehlt
+
+Im Vergleich zur `vagrant`-Inventory (Referenz) fehlen für eine
+vollständige Deployment:
+
+- `host_vars/application/main.yml` — Backbone-Vars für den Host
+  (FQDN-Pattern, gemeinsame Defaults).
+- `host_vars/application/{nextcloud,opencloud,authentik,authentik_outpost_ldap,collabora,drawio}.yml`
+  — die service-spezifischen Konfigurationen.
+- `host_vars/storage/{main.yml,garage.yml}` — Garage-Cluster-Setup.
+- `host_vars/reverseproxy/<…>.yml` mit `traefik_dmz_exposed_services`
+  — sonst routet die DMZ nichts.
+
+Die `vagrant`-Inventory ist das Template: dieselbe Struktur auf
+`application`/`storage` mappen, FQDNs auf `*.gymb.souveredu.ch`
+umstellen, Secrets durch Bao-Lookups ersetzen.