Digitalboard/docs
6
1
Fork 0
Code Pull requests 1 Activity Actions
docs/architecture/setup.md
Simon Bärlocher 345cf4b319
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.
2026-05-28 14:25:27 +02:00

2.6 KiB
Raw Blame History

Setup and repo layout

← Back to Architecture index

1. Repo layout and role provenance

reference-ansible/
├── Makefile                     # Deploy targets, OIDC login, OBJC fork workaround
├── ansible.cfg                  # collections_path, remote_user=root, hashi_vault auth_method=token
├── requirements.yml             # community.hashi_vault + digitalboard.core (Git)
├── playbooks/site.yml           # Play sequence (14 plays, see deploy.md)
├── collections/                 # ← installed by `make install`, gitignored
│   └── ansible_collections/
│       └── digitalboard/core/
│           └── roles/           # 🔑 Roles live HERE, NOT in the repo root
└── inventories/
    ├── demo-gymburgdorf/        # Inventory used throughout this document
    ├── demo-mbazürich/
    ├── demo-phbern/
    └── vagrant/                 # Local test inventory with its own topology

Important: There is no roles/ directory at the repo root. All roles come from the digitalboard.core collection (see requirements.yml), installed via make install into ./collections/. Plays reference them by FQCN digitalboard.core.<role>.

2. Setup and prerequisites

Tools on the control node:

  • ansible (Core ≥ 2.15)
  • bao CLI (OpenBao) — e.g. sudo pacman -S openbao python-hvac (Arch) or Homebrew
  • python-hvac (for community.hashi_vault lookups)
  • On macOS: OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES (set in the Makefile; without it Ansible forks crash on Bao lookups)

Initial setup:

git clone <repo>
cd reference-ansible
make install         # Galaxy + digitalboard.core into ./collections/

Before every deploy: Bao login in the same shell that will then run ansible-playbook:

export BAO_ADDR=https://bao.digitalboard.ch
bao login -method=oidc -path=Digitalboard
export VAULT_TOKEN=$(bao print token)

⚠️ make bao on its own is not enough: every make target spawns a new shell, and the VAULT_TOKEN exported in there only lives for the duration of make bao itself. Either run the three commands above manually, or invoke make bao deploy_site_demo_gymburgdorf as one call — otherwise the deploy has no token.

Smoke test:

make ping_demo       # pings all three demo inventories