---
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.
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, or a system service | Write plain tasks. Do not force the role | `banner.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.