Files

T

Lucas WintherandClaude Opus 5.5 665ac7d52f Render stack secrets from OpenBao in compose_stack

stack_secrets reads KV v2 on the target host and writes the stack's .env at
0600, failing loudly on a sealed vault, a bad token, a missing field or an
unsafe value. Adds an example OpenBao stack on app and moves webapp onto it;
metrics keeps a hand-placed .env.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

2026-09-30 15:15:04 +02:00

2.5 KiB

Raw Blame History

Contributing

Running the checks

One command, and it is the same one CI runs:

make check          # or: scripts/check.sh

It runs yamllint over the repository, installs the Galaxy collections, runs ansible-lint at the production profile, and syntax-checks every playbook.

Locally it reaches for uv so this repository needs no virtualenv of its own. If you already have the tools on PATH, use RUNNER=installed scripts/check.sh to skip that.

The version pins live in scripts/check.sh and nowhere else; both CI configurations ask the script for them, so a workflow cannot drift from what you ran locally.

Lint and syntax-check are the definition of done for a playbook. They are static and safe.

What the checks will not catch

Nothing here talks to a host, so the gate cannot tell you that a deploy works. Before proposing a change to a playbook, run it against your own host with --check --diff and say in the pull request what it reported. If you cannot, say that too — it is useful information, and better than an implied claim.

Conventions

They are in AGENTS.md, which is written for AI agents and is equally the contributor guide. The short version:

One playbook per stack, self-contained, tagged with the stack name.
Reuse goes in the compose_stack role's variable contract, not in copy-pasted tasks or a second role.
Modules, not shell. Fully-qualified collection names. Every task named.
A second run must report zero changes.
No secrets in the repository — not in a .env, and especially not inline in a compose file. See docs/secrets.md.

skills/adding-a-stack/SKILL.md is the step-by-step version for the most common change.

Changing the examples

The seven example stacks exist to demonstrate specific features of the role contract — the table in server/README.md says which. If you change one, check that whatever it was demonstrating is still demonstrated somewhere, or the documentation that points at it stops being true.

New examples are welcome if they show something the current seven do not. An example that shows the same thing an eighth way is a cost, not a contribution.

Reporting a security issue

Do not open a public issue for a vulnerability. Note that the example credentials, hostnames and addresses in this repository are all fictional; example.com is reserved by RFC 2606 and cannot resolve.

2.5 KiB Raw Blame History