docs/README.md

📚 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

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
digitalboard.core	Ansible collection — every reusable role (Traefik, Authentik, Keycloak, Nextcloud, Garage, …). The "what runs on a host."	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

🚀 Want to deploy something? Start in reference-ansible — its README covers the Bao login, the make targets, and the available playbooks. Come back here for the architectural background (architecture/) or for solved problems (troubleshooting/).

📖 Contents

• Architecture — How the reference-ansible deployment is structured, using demo-gymburgdorf as the running example.

  • Index & glossary
  • Setup and repo layout — control-node prerequisites, Bao login workflow
  • Variables — Ansible variable hierarchy and cheatsheet
  • Topology — Inventory groups, service layout per host
  • DNS and ACME — Knot zones, TSIG/ACL model, split-horizon FQDNs
  • Deploy — Play sequence, Traefik DMZ vs. backend modes
  • Security — Bao lookup pattern, demo-only defaults, production hardening
  • Operations — New-tenant walkthrough, known gaps

• Contributing — Conventions for collaborating on this codebase.

  • Git — Guidelines for contributing using git

• Infrastructure — Infrastructure-level concepts that apply across services.

  • ACME — Documentation of the ACME concept
  • IPv6 — Documentation of the IPv6 concept

• Keycloak — Keycloak configuration and best practices.

  • Account Linking — How to link existing accounts to a federated identity
  • Enforce OTP 2FA for Internal Users — OTP-based 2FA for internal users, excluding external MS Entra users
  • Integrate MS Entra in Keycloak as IDP — MS Entra as identity provider

• Microsoft Entra — Microsoft Entra configuration and best practices.

  • Enterprise App Integration with Keycloak — Enterprise App in MS Entra (Azure AD) as IDP for Keycloak

• Troubleshooting — Encountered & solved problems.

  • Nextcloud File Locking — 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
Set up a new demo tenant	architecture/operations.md
Look up a variable's correct home	architecture/variables.md
Understand why two ACME models coexist	architecture/dns.md
Plug an identity provider into Keycloak	keycloak/
Solve a recurring runtime issue	troubleshooting/

---

📝 Contributions follow the guidelines in contributing/git.md.