Simon Bärlocher 2ba0c07cd3

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. site.yml keeps a third traefik
play (traefik_servers minus the vagrant _dmz/_backend split) so the demo
inventories still configure their reverse proxy after the rebase onto main.

2026-05-28 11:20:54 +02:00

3.4 KiB

Raw Permalink Blame History

Getting Started

← Documentation index

From zero to your first deploy. This page walks through prerequisites, setup, and the first Ansible run. Deeper details are linked along the way.

Prerequisites

Access (to be set up out-of-band)

WKS account with OIDC access to OpenBao. The login runs via bao login -method=oidc -path=Digitalboard. Without an authorized account, authentication fails — and without a token there is no secret lookup, hence no deploy.
Bao policy / mount read. The account needs Read on the mount of the target inventory (e.g. demo-gymburgdorf/data/*). Which paths an inventory reads is documented in the host_vars/.../<service>.yml (see secrets.md § Secret pattern).
SSH key on the target hosts. The hosts are provisioned as root (ansible_user: root, no bastion/jump host). Your own public key must be placed out-of-band as root on the hosts.
Network access (VPN). bao.digitalboard.ch and the host networks (172.16.9.0/24 DMZ, 172.16.19.0/24 backend) are not publicly reachable — access requires VPN/network access into the Digitalboard network.

Tools on the control node

ansible (Core ≥ 2.15) — ansible --version to check
bao CLI (OpenBao) — e.g. sudo pacman -S openbao python-hvac (Arch) or via Homebrew
python-hvac (for community.hashi_vault lookups)
On macOS: OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES (set in the Makefile) — without this env var, Ansible forks crash on the first Bao lookup, because the Objective-C runtime is not fork-safe.

1. Clone the repo and install collections

git clone https://git.digitalboard.ch/Digitalboard/reference-ansible
cd reference-ansible
make install         # community.hashi_vault + digitalboard.core into ./collections/

There is no roles/ directory in the repo — all roles come from the digitalboard.core collection. See inventories.md § Repo layout.

2. Log in to OpenBao

The login must happen in the same shell in which ansible-playbook then runs — details and the make bao caveat in secrets.md § OpenBao login:

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

3. Check connectivity (smoke test)

make ping_demo       # ping module against all three demo inventories

If a host does not respond, it is usually due to the SSH key (prerequisite above) or missing network access (VPN).

4. Run Ansible (deploy)

make deploy_site_demo_gymburgdorf       # single demo site

At its core, make only calls ansible-playbook — the equivalent direct invocation:

ansible-playbook playbooks/site.yml \
  -i inventories/demo-gymburgdorf/hosts.yml --diff

All variants (direct invocation, --limit, --tags, check mode) and the make targets are documented in ansible.md § Running Ansible.

Next steps

What happens during a deploy? → ansible.md § Playbook
Create a new tenant → inventories.md § Walkthrough
Store secrets in Bao → secrets.md

3.4 KiB Raw Permalink Blame History