345cf4b319
- Move Simon's architecture documentation into architecture/ (setup, variables, topology, dns, deploy, security, operations plus index and glossary). All cross-repo references point at https://git.digitalboard.ch/Digitalboard/{reference-ansible,dns-zones} via absolute URLs so the docs remain navigable from any context. - Rewrite README.md as a documentation hub: introduction, platform Mermaid overview, comparison of the three repos (docs / digitalboard.core / reference-ansible) and a full table of contents covering architecture, contributing, infrastructure, keycloak, ms-entra and troubleshooting. Addresses the open items from the WKS PoC review (2026-05-26): docs README begrüssungstext + Übersichtsgrafik + Verlinkung der beiden anderen Repos, sowie das Verschieben der Architektur-Doku.
3.4 KiB
3.4 KiB
Architecture — reference-ansible
This documentation describes the architecture of the reference-ansible
repository and uses the inventory inventories/demo-gymburgdorf/ as a
running example. It serves both as onboarding documentation for new
engineers and as a reference when setting up additional demo tenants.
Demo-only. All defaults in the roles (passwords, tokens, RPC secrets) are insecure and intended exclusively for demo setups. See security.md.
Last updated: 2026-05-26 · Owner: @sbaerlocher
Contents
| Section | File | Topics |
|---|---|---|
| Setup and repo layout | setup.md | Repo layout, role provenance, control-node prerequisites, Bao login workflow |
| Variables | variables.md | Ansible variable hierarchy, variable cheatsheet |
| Topology | topology.md | Inventory groups, service layout per host, variable placement |
| DNS and ACME | dns.md | Knot zones, NS-delegated vs. ACL-isolated ACME models, split-horizon FQDNs, TSIG/ACL |
| Deploy | deploy.md | Play sequence, Traefik DMZ/backend modes |
| Security | security.md | Bao lookup pattern, demo-only defaults, threat boundaries, production hardening |
| Operations | operations.md | New-tenant walkthrough, known gaps and trade-offs |
Glossary
| Term | Meaning |
|---|---|
| OpenBao | HashiCorp Vault fork. Single source of truth for secrets. Endpoint: bao.digitalboard.ch. |
| Authentik | Identity provider. Issues OIDC for SP services and LDAP via the Outpost. |
| Outpost (Authentik) | Separate Authentik sidecar that emulates LDAP/proxy protocols for legacy apps. Talks to Authentik via RPC + token. |
| WOPI | Web Application Open Platform Interface — protocol used by Nextcloud/Opencloud to hand office documents to Collabora. |
| TSIG / RFC2136 | Authenticated DNS updates. Traefik uses TSIG-signed nsupdate calls for ACME DNS-01 challenges. |
| DNS-01 (ACME) | Let's Encrypt challenge type: certificate ownership is proven via a TXT record in DNS instead of HTTP. Required for wildcard certs. |
| CNAME bridge | _acme-challenge.<fqdn> points via CNAME into a dedicated update label (<service>.demo-gymb._acme.digitalboard.ch), keeping the TSIG key scoped to a narrow sub-tree. See dns.md. |
| Knot DNS | Authoritative DNS server used on ns1.digitalboard.ch. Config and zone files live in the separate dns-zones repo. |
| DNSSEC | Zones are signed with Ed25519, NSEC3 (no opt-out), KSK 1y / ZSK 90d rollovers, CDS/CDNSKEY published for automatic DS at the parent. |
| Split horizon | Two FQDN families per service: public <svc>.gymb.souveredu.ch → DMZ Traefik front-end IP, internal <svc>.int.gymb.souveredu.ch → directly the backend host. See dns.md. |
| File provider / Docker provider | Traefik configuration sources. The file provider reads static YAML; the Docker provider reads container labels via /var/run/docker.sock. |
| STUN/TURN | NAT-traversal protocols for WebRTC (e.g. for Nextcloud Talk). Runs on a separate host (turn). |
| Garage | S3-compatible object store (Rust). Backend for Nextcloud/Opencloud. |
| FQCN | Fully Qualified Collection Name, e.g. digitalboard.core.traefik. Mandatory in Ansible since 2.10. |