config-public/skills/adding-a-stack/SKILL.md

name, description

name	description
adding-a-stack	Use when adding a new service to this repository, moving a service to a different host, or bringing a hand-deployed service under Ansible and CI.

Adding a stack

A stack is one Docker Compose deployment on one host. Adding one touches four files and one button. AGENTS.md holds the conventions and the full compose_stack role contract — read it first; this file is the order of work.

Steps

1. Payload. Put the compose file and its configuration in server/<host>/<stack>/. Payloads are copied verbatim, so do not template or restructure them. Never commit a .env, a key, or a secret written inline in a compose file — read docs/secrets.md before you decide something is fine to commit.

2. Playbook. Create ansible/playbooks/<stack>.yml. Copy static-site.yml; most stacks are a name and a network. Tag the play with the stack name.

3. Register it. Add an import_playbook entry to ansible/playbooks/site.yml in dependency order — the reverse proxy owns proxy-net and the vhost configuration, so it stays first.

4. Give it a button. All three CI configurations need the stack by name, and none of them can generate the list:

   • .github/workflows/deploy.yml — add it to the stack input's options:.
   • .gitea/workflows/deploy.yml — the same options: list again. Gitea reads .gitea/workflows/ instead of .github/workflows/, so the two files are never both in play and never both wrong at once — which is exactly why one of them gets forgotten.
   • .gitlab-ci.yml — add a check:<stack> and deploy:<stack> pair extending .check and .deploy; copy the pair above them, three lines each. Pin the stack with STACK_FIXED, never STACK — a pipeline variable outranks a job's YAML variables:, so a button named with STACK is hijacked by any pipeline triggered with a different one.

   Delete whichever platforms you are not using rather than letting them rot.

5. Verify statically. make check from the repository root. It must pass; this is the definition of done for the playbook.

6. Deploy. Run the check mode, read the diff, then deploy. Never run a playbook against a host unless the person you are working with asked for it in that turn.

Does it fit the shared role?

If	Do	Example
It is not a Compose stack — one file into another stack's directory, host preparation, or a system service	Write plain tasks. Do not force the role	banner.yml, bootstrap.yml
Something must happen between the payload landing and the stack starting (backup, migration)	Use the two entry points, tasks_from: sync then tasks_from: up, and gate the middle on pull | default('policy') == 'always'	webapp.yml
The payload is bind-mounted config, which Compose never recreates a container for	Add a post_tasks reload keyed on compose_stack_synced	reverse-proxy.yml, metrics.yml
The compose file is not named docker-compose.yml, or there are several	stack_files	webapp.yml
The same payload serves several hosts, or several instances	stack_src, and stack_dest for the second instance	metrics.yml, webapp-staging.yml
The stack needs a .env that is deliberately never shipped	stat + assert that it exists on the host first	webapp.yml
It needs an external Docker network	stack_networks	any of them
A bind mount would otherwise be created root-owned by Docker	stack_dirs; omit mode so an existing directory is left alone	reverse-proxy.yml
A bind mount must be owned by a uid from inside the container	stack_dirs with owner/group and recurse, and no mode	metrics.yml
The image is built from a Dockerfile in the payload	stack_build, set to always only on an update run	webapp.yml
Hosts differ in some small way	A dict keyed by inventory_hostname, looked up in the role vars	metrics.yml

Extend the role's variable contract rather than adding a second role or loose tasks. If a stack needs something the contract cannot express, say so instead of working around it — that is information about the contract.

Common mistakes

• Skipping step 3 or 4. The stack then works from a workstation and is invisible in CI, which is exactly how services end up hand-deployed and undocumented. This is the most common failure and the least visible.
• Pre-creating a Postgres data directory in stack_dirs. Postgres refuses to start unless it is 0700 or 0750, so leave it to the image.
• Setting mode on a bind mount that already has data. It rewrites the permissions of everything the container has written there. Set owner/group with recurse instead, and no mode.
• A pre_tasks chown instead of stack_dirs. pre_tasks run before the stack directory exists, and the escalated file task stamps its owner onto every parent it creates — leaving the payload sync unable to write into the stack's own directory.
• Expecting .env to reach the host. It is excluded from every sync by design. Secrets live on the host.
• A reload task with no when: compose_stack_synced. Every run then reports a change, the playbook is never idempotent, and changed=0 stops meaning anything.
• Putting the stack_* vars inside roles: for a two-phase playbook. They are scoped to that invocation and the second include_role will not see them. Declare them at play level.