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.
This commit is contained in:
parent
c67e9aac43
commit
2ba0c07cd3
24 changed files with 1541 additions and 525 deletions
93
docs/testing.md
Normal file
93
docs/testing.md
Normal file
|
|
@ -0,0 +1,93 @@
|
|||
<!-- markdownlint-disable MD013 -->
|
||||
# Testing
|
||||
|
||||
[← Documentation index](README.md)
|
||||
|
||||
> **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`](https://git.digitalboard.ch/Digitalboard/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:
|
||||
|
||||
```bash
|
||||
# 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](#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](secrets.md#openbao-login)):
|
||||
|
||||
```bash
|
||||
# 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](getting_started.md#prerequisites):
|
||||
|
||||
```bash
|
||||
# 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](ansible.md#running-ansible).
|
||||
|
||||
## Recommended pre-deploy workflow
|
||||
|
||||
```bash
|
||||
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`](https://git.digitalboard.ch/Digitalboard/digitalboard.core),
|
||||
not in this repo.
|
||||
Loading…
Add table
Add a link
Reference in a new issue