docs(reference-ansible): add docs/ tree and document repo, playbooks, Makefile
Addresses the WKS PoC review (Notion 2026-05-26). All docs in English. - README: purpose, docs table of contents, annotated repo tree - docs/getting_started.md: prerequisites (WKS account, OIDC, SSH, VPN) + first deploy - docs/ansible.md: playbook table, "Running Ansible", service parameters, cheatsheet - docs/secrets.md: canonical Bao login (moved out of README) + demo defaults - docs/operations.md: full Makefile reference - docs/inventories.md: repo layout, topology, standard folder structure, walkthrough - docs/testing.md: static checks, inventory resolution, smoke test / dry run - remove ARCHITECTURE.md (architecture docs live externally) Also includes the gymburgdorf inventory build-out (bookstack, homarr, opnform, send) and scripts/bao-seed.sh. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Simon Bärlocher
parent
b59b2df82a
commit
ae4eb799bb
25 changed files with 1530 additions and 517 deletions
132
README.md
132
README.md
|
|
@ -1,61 +1,117 @@
|
|||
<!-- markdownlint-disable MD013 -->
|
||||
# reference-ansible
|
||||
|
||||
Ansible-Setup für Demo-Deployments (`demo-gymburgdorf`,
|
||||
`demo-mbazürich`, `demo-phbern`) und lokale Vagrant-Tests. Rollen
|
||||
kommen aus der Collection
|
||||
## Purpose
|
||||
|
||||
This repository is the **Ansible setup for the Digitalboard demo
|
||||
deployments** — reproducible reference tenants on which the full stack
|
||||
(identity, storage, office, forms, dashboards, …) can be set up and
|
||||
demonstrated end-to-end.
|
||||
|
||||
It contains **no** roles of its own: all logic comes from the collection
|
||||
[`digitalboard.core`](https://git.digitalboard.ch/Digitalboard/digitalboard.core)
|
||||
(via [requirements.yml](requirements.yml)).
|
||||
(via [requirements.yml](requirements.yml)). What lives here is the
|
||||
**inventory and configuration layer** — one dedicated inventory per
|
||||
tenant under `inventories/demo-*` that wires up the roles, defines hosts
|
||||
and domains, and pulls secrets from [OpenBao](https://openbao.org/). The
|
||||
only playbook is [playbooks/site.yml](playbooks/site.yml).
|
||||
|
||||
> Architektur, Variablen-Hierarchie, Service-Topologie und der
|
||||
> Walkthrough zum Aufsetzen neuer Mandanten: siehe
|
||||
> **[ARCHITECTURE.md](ARCHITECTURE.md)**.
|
||||
The repository thus serves two purposes:
|
||||
|
||||
## Voraussetzungen
|
||||
- **Demo operation:** deploy and keep up to date the existing demo
|
||||
tenants (`demo-gymburgdorf`, `demo-mbazürich`, `demo-phbern`).
|
||||
- **Template:** create new tenants following the `demo-gymburgdorf`
|
||||
pattern — see [docs/inventories.md § Walkthrough](docs/inventories.md#walkthrough-creating-a-new-demo-tenant).
|
||||
|
||||
- `ansible` (Core ≥ 2.15)
|
||||
- `bao` CLI ([OpenBao](https://openbao.org/)) — z. B.
|
||||
`sudo pacman -S openbao python-hvac` (Arch) oder Homebrew
|
||||
- `python-hvac` (für `community.hashi_vault` Lookups)
|
||||
> **Demo-only.** All role defaults (passwords, tokens, RPC secrets) are
|
||||
> insecure and intended exclusively for demo setups. For production
|
||||
> adaptation, see [docs/secrets.md](docs/secrets.md).
|
||||
|
||||
## Setup
|
||||
## Documentation
|
||||
|
||||
```bash
|
||||
make install # installiert digitalboard.core + community.hashi_vault nach ./collections/
|
||||
In-depth documentation lives in the [`docs/`](docs/) folder — start with
|
||||
the index [docs/README.md](docs/README.md):
|
||||
|
||||
| Document | Content |
|
||||
| --- | --- |
|
||||
| [docs/getting_started.md](docs/getting_started.md) | Prerequisites (access, tools), first deploy step by step |
|
||||
| [docs/operations.md](docs/operations.md) | Setup, prerequisites, deploy flow, make targets, smoke test, known gaps |
|
||||
| [docs/secrets.md](docs/secrets.md) | OpenBao login, secret lookup pattern, demo-only defaults, threat boundaries |
|
||||
| [docs/inventories.md](docs/inventories.md) | Repository layout, roles origin, inventory topology, new-tenant walkthrough |
|
||||
| [docs/ansible.md](docs/ansible.md) | Playbooks (`site.yml`), service parameters, variable cheat sheet |
|
||||
| [docs/testing.md](docs/testing.md) | Static checks, inventory resolution, smoke test/dry run before the deploy |
|
||||
|
||||
## Repository structure
|
||||
|
||||
```text
|
||||
reference-ansible/
|
||||
├── Makefile # deploy targets, OIDC login, OBJC fork workaround
|
||||
├── ansible.cfg # collections_path, remote_user=root, hashi_vault auth
|
||||
├── requirements.yml # community.hashi_vault + digitalboard.core (Git)
|
||||
├── Vagrantfile # local test VMs
|
||||
├── playbooks/
|
||||
│ └── site.yml # the only playbook — play sequence of all services
|
||||
├── scripts/
|
||||
│ └── bao-seed.sh # seed/merge OpenBao secrets per inventory (idempotent)
|
||||
├── docs/ # in-depth documentation (see table above)
|
||||
├── collections/ # ← installed by `make install`, gitignored
|
||||
│ └── ansible_collections/digitalboard/core/roles/ # 🔑 the roles live here
|
||||
└── inventories/
|
||||
├── demo-gymburgdorf/ # reference tenant — template for new tenants
|
||||
│ ├── hosts.yml # hosts + group topology
|
||||
│ ├── group_vars/ # all/ · traefik_servers/ · backend_servers/
|
||||
│ └── host_vars/ # reverseproxy/ · application/ · storage/
|
||||
├── demo-mbazürich/ # demo tenant
|
||||
├── demo-phbern/ # demo tenant
|
||||
└── vagrant/ # local test inventory (incompatible topology)
|
||||
```
|
||||
|
||||
## Secrets (OpenBao)
|
||||
> **No `roles/` in the repository root** — all roles come from
|
||||
> `digitalboard.core` and are installed via `make install` into
|
||||
> `./collections/`. Plays reference them by FQCN
|
||||
> `digitalboard.core.<role>`. Details:
|
||||
> [docs/inventories.md](docs/inventories.md#repo-layout-and-role-origin).
|
||||
|
||||
Vor jedem Deploy in **derselben Shell** authentisieren:
|
||||
## Quick Start
|
||||
|
||||
> **First time here?** Prerequisites (WKS account, OIDC access, SSH key,
|
||||
> VPN), tool setup, and the first deploy step by step:
|
||||
> **[docs/getting_started.md](docs/getting_started.md)**.
|
||||
|
||||
```bash
|
||||
make install # collections into ./collections/
|
||||
|
||||
# Log in to OpenBao — in the SAME shell as the deploy.
|
||||
# Full login flow + make-bao caveat: docs/secrets.md
|
||||
export BAO_ADDR=https://bao.digitalboard.ch
|
||||
bao login -method=oidc -path=Digitalboard
|
||||
export VAULT_TOKEN=$(bao print token)
|
||||
|
||||
make ping_demo # smoke test against all demo inventories
|
||||
make deploy_site_demo_gymburgdorf # single demo site
|
||||
make deploy_site_demo # all three demo sites
|
||||
```
|
||||
|
||||
> ⚠️ `make bao` allein reicht **nicht** — jedes `make`-Target läuft in
|
||||
> einer neuen Shell, der dort gesetzte `VAULT_TOKEN` lebt nur während
|
||||
> `make bao` selbst. Entweder die drei Befehle oben manuell im Shell
|
||||
> ausführen oder `make bao deploy_site_demo_gymburgdorf` als **einen**
|
||||
> Aufruf chainen.
|
||||
Login details and the `make bao` caveat: [docs/secrets.md](docs/secrets.md#openbao-login).
|
||||
Prerequisites, all make targets, and the deploy flow:
|
||||
[docs/operations.md](docs/operations.md). Invoking Ansible directly
|
||||
(`--limit`, `--check`): [docs/ansible.md § Running Ansible](docs/ansible.md#running-ansible).
|
||||
|
||||
## Deploy
|
||||
## Available playbooks
|
||||
|
||||
```bash
|
||||
make ping_demo # Smoke-Test gegen alle Demo-Inventories
|
||||
make deploy_site_demo_gymburgdorf # einzelnes Demo-Site
|
||||
make deploy_site_demo # alle drei Demo-Sites
|
||||
```
|
||||
|
||||
Auf macOS setzt das [Makefile](Makefile) zusätzlich
|
||||
`OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` — ohne diese Env-Var
|
||||
crashen Ansible-Forks beim ersten `community.hashi_vault`-Lookup.
|
||||
The only playbook is [playbooks/site.yml](playbooks/site.yml) — a
|
||||
sequence of plays, each applying one `digitalboard.core` role to a host
|
||||
group (base, traefik, garage, authentik, authentik_outpost_ldap,
|
||||
nextcloud, collabora, drawio, send, opnform, homarr, bookstack, …).
|
||||
Which plays take effect in an inventory is governed solely by group
|
||||
membership in `hosts.yml`. Full play table and all service parameters:
|
||||
**[docs/ansible.md](docs/ansible.md)**.
|
||||
|
||||
## Inventories
|
||||
|
||||
| Inventory | Zweck |
|
||||
|---|---|
|
||||
| [`inventories/demo-gymburgdorf/`](inventories/demo-gymburgdorf/) | Demo-Mandant — als Vorlage für neue Mandanten empfohlen, siehe [ARCHITECTURE.md § 10](ARCHITECTURE.md#10-walkthrough-neuen-demo-mandanten-anlegen) |
|
||||
| [`inventories/demo-mbazürich/`](inventories/demo-mbazürich/) | Demo-Mandant |
|
||||
| [`inventories/demo-phbern/`](inventories/demo-phbern/) | Demo-Mandant |
|
||||
| [`inventories/vagrant/`](inventories/vagrant/) | lokale Test-VMs; **inkompatible Gruppen-Topologie** zu den Demo-Inventories |
|
||||
| Inventory | Purpose |
|
||||
| --- | --- |
|
||||
| [`inventories/demo-gymburgdorf/`](inventories/demo-gymburgdorf/) | Demo tenant — recommended as a template for new tenants, see [docs/inventories.md](docs/inventories.md#walkthrough-creating-a-new-demo-tenant) |
|
||||
| [`inventories/demo-mbazürich/`](inventories/demo-mbazürich/) | Demo tenant |
|
||||
| [`inventories/demo-phbern/`](inventories/demo-phbern/) | Demo tenant |
|
||||
| [`inventories/vagrant/`](inventories/vagrant/) | Local test VMs; **incompatible group topology** compared to the demo inventories |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue