345cf4b319
- 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.
68 lines
2.6 KiB
Markdown
68 lines
2.6 KiB
Markdown
<!-- markdownlint-disable MD013 MD060 MD051 -->
|
|
# Setup and repo layout
|
|
|
|
← Back to [Architecture index](README.md)
|
|
|
|
## 1. Repo layout and role provenance
|
|
|
|
```text
|
|
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](https://git.digitalboard.ch/Digitalboard/reference-ansible/src/branch/main/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](https://git.digitalboard.ch/Digitalboard/reference-ansible/src/branch/main/Makefile); without it Ansible forks crash on Bao lookups)
|
|
|
|
**Initial setup:**
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
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:**
|
|
|
|
```bash
|
|
make ping_demo # pings all three demo inventories
|
|
```
|