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

---
name: adding-a-stack
description: 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.

   If the stack needs a credential, put it in OpenBao now and ship a
   `.env.example` listing the variable names. Pipe the value in on stdin rather
   than passing `<field>=<value>`, which lands it in the host's process table
   and your shell history, and strip the trailing newline — `<field>=-` stores
   stdin byte for byte and the role refuses a value containing one:

   ```bash
   openssl rand -hex 32 | tr -d '\n' \
     | docker exec -i openbao bao kv put kv/stacks/<stack> <field>=-
   ```
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, and `openbao` must come before any stack
   that sets `stack_secrets`.
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.
   Leave a stack out only if it must never deploy from CI — see the table below.
5. **Group it, if it belongs in one.** Add it to a line in
   `server/<host>/stack-groups` so `stackctl up <group>` on that host includes
   it. Optional: `stackctl all` finds every stack regardless.
6. **Verify statically.** `make check` from the repository root. It must pass;
   this is the definition of done for the playbook.
7. **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, a precondition) | Use the two entry points, `tasks_from: sync` then `tasks_from: up`, and gate the middle on `pull \| default('policy') == 'always'` or `compose_stack_synced` | `webapp.yml` |
| It is replacing a hand-deployed instance whose data must be copied in first | `-e start=false`, copy the data into the bind mounts, then deploy normally. Write the steps into the playbook's header comment | none — see "Deploying without starting" in `AGENTS.md` |
| 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` |
| …but a restart is itself disruptive (a vault that seals, a runner that kills its own job) | Report on `compose_stack_synced` instead of restarting, and let a person choose when | `openbao.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 credential | `stack_secrets`, naming the vault path and field for each variable. Put the value in OpenBao first | `webapp.yml` — see the contract in `AGENTS.md` and `docs/secrets.md` |
| The stack needs a `.env` placed by hand, on a host with no vault | `stat` + `assert` that it exists on the host first | `metrics.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`. The host needs `bootstrap.yml -e deploy_sudo=true` | `metrics.yml`, `openbao.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` |
| Deploying it from CI would kill the CI job — the runner itself, or whatever the runner depends on | Leave it out of `site.yml` and the deploy form, and assert in `pre_tasks` that `GITHUB_ACTIONS`, `GITEA_ACTIONS` and `GITLAB_CI` are not `true` — the dispatch API accepts any stack with a playbook | none here |

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. Use `stack_secrets`, or place it on the host by hand.
- **Storing a vault value with a trailing newline.** `bao kv put ... field=-`
  keeps the newline from `echo` or `openssl rand`, and the role refuses to
  render it. Pipe through `tr -d '\n'`.
- **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.
- **Committing an upstream example compose file without reading it.** They are
  written for a quick start, not for a host. Look for three things: a password
  given as a default (`${POSTGRES_PASSWORD:-changeme}`), which is a committed
  secret — make it `${VAR:?}` and use `stack_secrets`; database or cache ports
  published on every interface, which nothing outside the stack needs; and
  `KEY:value` entries in a list-form `environment:`, which set a variable
  literally named `KEY:value` and nothing else — the list form needs `=`.
- **A stateful service with no bind mount.** An app that falls back to SQLite
  inside its container loses everything the next time Compose recreates it. Find
  where it writes and mount that directory; if the image runs as a fixed uid,
  give the directory to it with `stack_dirs`.
- **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.