docs: add architecture section and overhaul top-level README
- 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
parent
8c2ea8cc72
commit
345cf4b319
9 changed files with 742 additions and 27 deletions
122
README.md
122
README.md
|
|
@ -1,35 +1,103 @@
|
|||
# 📚 Documentation Repository
|
||||
<!-- markdownlint-disable MD013 MD060 -->
|
||||
# 📚 Digitalboard Documentation
|
||||
|
||||
This repository contains documentation, guides, and reference material.
|
||||
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.
|
||||
|
||||
## 📖 Available Documentation
|
||||
## 🏛️ Platform at a glance
|
||||
|
||||
- **[Contribution guidelines](./contributing/)**
|
||||
Documentation and guides related to infrastructure configuration and best practices.
|
||||
- [Git](./contributing/git.md)
|
||||
Guidelines for contributing using git
|
||||
```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
|
||||
|
||||
- **[Infrastructure](./infrastructure/)**
|
||||
Documentation and guides related to infrastructure configuration and best practices.
|
||||
- [ACME](./infrastructure/acme.md)
|
||||
Documentation of the ACME concept.
|
||||
- [IPV6](./infrastructure/ipv6.md)
|
||||
Documentation of the ipv6 concept.
|
||||
User((Operator / Engineer))
|
||||
|
||||
- **[Keycloak](./keycloak/)**
|
||||
Documentation and guides related to Keycloak configuration and best practices.
|
||||
- [Enforce OTP 2FA for Internal Users](./keycloak/enforce-otp-internal.md)
|
||||
Step-by-step instructions for enforcing OTP-based two-factor authentication for internal users, while excluding external Microsoft Entra users.
|
||||
- [Integrate MS Entra in Keycloak as IDP](./keycloak/idp-ms-entra.md)
|
||||
Step-by-step instructions for integrating MS Entra as identity-provider.
|
||||
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
|
||||
|
||||
- **[Microsoft Entra](./ms-entra/)**
|
||||
Documentation and guides related to Microsft Entra configuration and best practices.
|
||||
- [Enterprise App Integration with Keycloak](./ms-entra/enterprise-app-keycloak.md)
|
||||
Step-by-step instructions for creating an Enterprise Application in Microsoft Entra (Azure AD) as an identity provider for Keycloak.
|
||||
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
|
||||
|
||||
- **[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.
|
||||
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).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue