docs/README.md

<!-- markdownlint-disable MD013 MD060 -->
# 📚 Digitalboard Documentation

Welcome — this repository is the **central documentation hub** for the
Digitalboard platform. It collects architecture notes, operational
runbooks, integration guides, and troubleshooting recipes that span
multiple repositories, so they have one stable home instead of being
scattered across READMEs.

## 🏛️ Platform at a glance

```mermaid
flowchart LR
    classDef docs fill:#dbeafe,stroke:#1e40af,color:#000
    classDef core fill:#dcfce7,stroke:#166534,color:#000
    classDef ans  fill:#fef3c7,stroke:#92400e,color:#000
    classDef ext  fill:#e9d5ff,stroke:#6b21a8,color:#000

    User((Operator / Engineer))

    subgraph REPOS["Digitalboard repositories"]
        DOCS["<b>docs</b><br/>📖 architecture, runbooks,<br/>integration guides<br/>(this repo)"]:::docs
        CORE["<b>digitalboard.core</b><br/>⚙️ Ansible collection<br/>= all roles<br/>(traefik, authentik, nextcloud,<br/>garage, keycloak, …)"]:::core
        REF["<b>reference-ansible</b><br/>🚀 inventories + playbooks<br/>(demo-gymburgdorf,<br/>demo-phbern, demo-mbazürich,<br/>vagrant)"]:::ans
    end

    subgraph PLATFORM["Runtime targets"]
        BAO["OpenBao<br/>bao.digitalboard.ch<br/>(secrets)"]:::ext
        DNS["Knot DNS<br/>ns1.digitalboard.ch<br/>(ACME / split-horizon)"]:::ext
        HOSTS["Tenant VMs<br/>(reverseproxy · application ·<br/>storage · turn)"]:::ext
    end

    User -->|reads| DOCS
    User -->|runs `make deploy_…`| REF
    REF -->|requires| CORE
    REF -.->|hashi_vault lookups.-> BAO
    REF -->|ansible-playbook| HOSTS
    HOSTS -.->|nsupdate TSIG / ACME DNS-01.-> DNS
    HOSTS -.->|hashi_vault lookups.-> BAO
    DOCS -.documents.-> REF
    DOCS -.documents.-> CORE
```

**The three repos at a glance:**

| Repo | Role | Link |
|---|---|---|
| **`docs`** *(here)* | Architecture, integration guides, runbooks, troubleshooting. The "why" and the "how it fits together." | [git.digitalboard.ch/Digitalboard/docs](https://git.digitalboard.ch/Digitalboard/docs) |
| **`digitalboard.core`** | Ansible collection — every reusable role (Traefik, Authentik, Keycloak, Nextcloud, Garage, …). The "what runs on a host." | [git.digitalboard.ch/Digitalboard/digitalboard.core](https://git.digitalboard.ch/Digitalboard/digitalboard.core) |
| **`reference-ansible`** | Inventories + playbooks for the demo tenants and the `vagrant` test setup. The "what gets deployed where, with which variables." | [git.digitalboard.ch/Digitalboard/reference-ansible](https://git.digitalboard.ch/Digitalboard/reference-ansible) |

> 🚀 **Want to deploy something?** Start in
> [`reference-ansible`](https://git.digitalboard.ch/Digitalboard/reference-ansible) —
> its README covers the Bao login, the `make` targets, and the available
> playbooks. Come back here for the architectural background
> ([architecture/](./architecture/)) or for solved problems
> ([troubleshooting/](./troubleshooting/)).

## 📖 Contents

- **[Architecture](./architecture/)** — How the `reference-ansible`
  deployment is structured, using `demo-gymburgdorf` as the running example.
  - [Index & glossary](./architecture/README.md)
  - [Setup and repo layout](./architecture/setup.md) — control-node prerequisites, Bao login workflow
  - [Variables](./architecture/variables.md) — Ansible variable hierarchy and cheatsheet
  - [Topology](./architecture/topology.md) — Inventory groups, service layout per host
  - [DNS and ACME](./architecture/dns.md) — Knot zones, TSIG/ACL model, split-horizon FQDNs
  - [Deploy](./architecture/deploy.md) — Play sequence, Traefik DMZ vs. backend modes
  - [Security](./architecture/security.md) — Bao lookup pattern, demo-only defaults, production hardening
  - [Operations](./architecture/operations.md) — New-tenant walkthrough, known gaps

- **[Contributing](./contributing/)** — Conventions for collaborating on this codebase.
  - [Git](./contributing/git.md) — Guidelines for contributing using git

- **[Infrastructure](./infrastructure/)** — Infrastructure-level concepts that apply across services.
  - [ACME](./infrastructure/acme.md) — Documentation of the ACME concept
  - [IPv6](./infrastructure/ipv6.md) — Documentation of the IPv6 concept

- **[Keycloak](./keycloak/)** — Keycloak configuration and best practices.
  - [Account Linking](./keycloak/account-linking.md) — How to link existing accounts to a federated identity
  - [Enforce OTP 2FA for Internal Users](./keycloak/enforce-otp-internal.md) — OTP-based 2FA for internal users, excluding external MS Entra users
  - [Integrate MS Entra in Keycloak as IDP](./keycloak/idp-ms-entra.md) — MS Entra as identity provider

- **[Microsoft Entra](./ms-entra/)** — Microsoft Entra configuration and best practices.
  - [Enterprise App Integration with Keycloak](./ms-entra/enterprise-app-keycloak.md) — Enterprise App in MS Entra (Azure AD) as IDP for Keycloak

- **[Troubleshooting](./troubleshooting/)** — Encountered & solved problems.
  - [Nextcloud File Locking](./troubleshooting/nextcloud-file-locking.md) — Preventing sync conflicts when multiple users edit the same file via the Nextcloud desktop client

## 🧭 Where to look

| If you want to… | Go to |
|---|---|
| Understand how a tenant is wired up | [architecture/topology.md](./architecture/topology.md) |
| Set up a new demo tenant | [architecture/operations.md](./architecture/operations.md) |
| Look up a variable's correct home | [architecture/variables.md](./architecture/variables.md) |
| Understand why two ACME models coexist | [architecture/dns.md](./architecture/dns.md) |
| Plug an identity provider into Keycloak | [keycloak/](./keycloak/) |
| Solve a recurring runtime issue | [troubleshooting/](./troubleshooting/) |

---

📝 Contributions follow the guidelines in [contributing/git.md](./contributing/git.md).