<!-- markdownlint-disable MD013 MD060 MD051 -->
# 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](security.md).

**Last updated:** 2026-05-26 · **Owner:** @sbaerlocher

## Contents

| Section | File | Topics |
|---|---|---|
| Setup and repo layout | [setup.md](setup.md) | Repo layout, role provenance, control-node prerequisites, Bao login workflow |
| Variables | [variables.md](variables.md) | Ansible variable hierarchy, variable cheatsheet |
| Topology | [topology.md](topology.md) | Inventory groups, service layout per host, variable placement |
| DNS and ACME | [dns.md](dns.md) | Knot zones, NS-delegated vs. ACL-isolated ACME models, split-horizon FQDNs, TSIG/ACL |
| Deploy | [deploy.md](deploy.md) | Play sequence, Traefik DMZ/backend modes |
| Security | [security.md](security.md) | Bao lookup pattern, demo-only defaults, threat boundaries, production hardening |
| Operations | [operations.md](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](dns.md). |
| **Knot DNS** | Authoritative DNS server used on `ns1.digitalboard.ch`. Config and zone files live in the separate [`dns-zones`](https://git.digitalboard.ch/Digitalboard/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](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. |