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.3 KiB

Raw Blame History

Testing

← Documentation index

Status: This repo contains no automated test suite and no CI pipeline. It is the inventory/configuration layer — the testable logic (roles) lives in digitalboard.core. Role tests (Molecule or similar) therefore belong in the core repo, not here.

What is sensibly testable here are inventory and playbook errors before the actual deploy. There are three levels for that — from fast and risk-free to fully against the hosts.

1. Static checks (no host access needed)

No VAULT_TOKEN, no network access required:

# YAML syntax of all inventory files
yamllint inventories/

# Ansible best-practice lint over the playbook
ansible-lint playbooks/site.yml

# Playbook syntax + inventory parsing (does not yet resolve Bao lookups)
ansible-playbook playbooks/site.yml \
  -i inventories/demo-gymburgdorf/hosts.yml --syntax-check

yamllint and ansible-lint are not preconfigured in the repo — they run with their defaults. If project-wide rules are desired, a .yamllint/.ansible-lint in the repo root would be the place for it (see Open items).

2. Inspect inventory resolution

Shows the effectively merged variables per host — useful for seeing precedence surprises (group_vars vs. host_vars) before the deploy. Bao lookups are evaluated here, so VAULT_TOKEN is needed (see secrets.md):

# group/host structure as a tree
ansible-inventory -i inventories/demo-gymburgdorf/hosts.yml --graph

# all vars of a host (merged)
ansible-inventory -i inventories/demo-gymburgdorf/hosts.yml --host application

3. Smoke test & dry run (against the hosts)

Requires SSH access and VAULT_TOKEN — for prerequisites see getting_started.md:

# reachability of all demo hosts (ping module)
make ping_demo

# dry run: shows what WOULD change, without writing
ansible-playbook playbooks/site.yml \
  -i inventories/demo-gymburgdorf/hosts.yml --check --diff

--check is only of limited value with the Docker-Compose-based roles: some tasks report "changed" because they only know the real container state at runtime. As a plausibility check (does the playbook run through, are the vars correct?) it is still useful. More on the invocation variants: ansible.md § Running Ansible.

Recommended pre-deploy workflow

yamllint inventories/ && ansible-lint playbooks/site.yml      # 1. static
ansible-playbook playbooks/site.yml -i <inv>/hosts.yml --syntax-check
make ping_demo                                                 # 2. reachability
ansible-playbook playbooks/site.yml -i <inv>/hosts.yml --check --diff   # 3. dry run
# only then: real deploy

Open items

No CI — lint/syntax checks run only manually. A Gitea/ CI workflow that runs the static checks from level 1 on every push would be the next step.
No lint configuration — yamllint/ansible-lint run with defaults; project-wide rules (.yamllint, .ansible-lint) are missing.
Role tests — belong in digitalboard.core, not in this repo.

3.3 KiB Raw Blame History