2ba0c07cd3
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.
93 lines
3.3 KiB
Markdown
93 lines
3.3 KiB
Markdown
<!-- 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.
|