Digitalboard/docs
6
1
Fork 0
Code Pull requests 1 Activity Actions

docs: add architecture section and overhaul top-level README

Browse source 
- 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.
This commit is contained in:
Simon Bärlocher 2026-05-28 14:25:27 +02:00
parent 8c2ea8cc72
commit 345cf4b319
No known key found for this signature in database
GPG key ID: 63DE20495932047A
9 changed files with 742 additions and 27 deletions
Download patch file Download diff file Expand all files Collapse all files

44
architecture/README.md Normal file
View file

@ -0,0 +1,44 @@
<!-- 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. |