# Adding a new stack to brencher A "stack" is one self-contained Docker Swarm service that brencher manages end-to-end: detect HEAD changes, build, deploy, and expose service status to the UI. This file documents how to wire one up so it picks up commits without an operator clicking "Update" in the UI every time. ## Repository layout Brencher looks at exactly one commit on one ref per environment. For a new stack `my_stack`: 1. Push branch `feat/my_stack` (or whatever the team convention is) to a Git repo listed in `remotes` of the config file. 2. Drop the repo in `gitea` or `github` so it's reachable through the same remotes that other stacks use. 3. Make sure `my_stack/stack-compose.yml` and a Dockerfile (typically `my_stack/Dockerfile`) exist at the path the config will point at. ## Config file: `backend/configs/.py` The shape is fixed by `enironment.Environment` and the steps it pulls in. Look at `backend/configs/hermes.py` for the canonical pattern. A new config must: - Build a `GitClone` with at least one remote whose `url` points to the repo above. - Build a `DockerSwarmCheck(stack_name="")` to introspect the deployed service. - Build **`GitUnmerge(clone, dockerSwarmCheck)`** and wrap it into `SharedStateHolderInMemory(unmerge=unmerge)`. This is what makes autodeploy work — `GitUnmerge` reads the `org.brencher.version` label from the running swarm task and converts it into `desired_branches`, so each polling cycle asks "is HEAD ≠ what's deployed?" without any UI input. - Wire a `CheckoutMerged(clone, desired_branches=state, push=False, …)`. Push stays `False` for first-party stacks; set `True` only when you want brencher to push auto-named branches back to origin. - Build a `DockerComposeBuild` (or `DockerSwarmBuild` if a Swarmfile is used) pointing at the compose path in the repo. - Build a `DockerSwarmDeploy(wd=clone, buildDocker=…, stackChecker=…, …)` with the same `stack_name`. Image tag is `auto-` driven by `checkoutMerged.progress().version`. - Optionally append a `SimpleLog(message={"userLinks": {...}})` for the link to surface in the UI. - Set `__all__` and export the `Environment` named after the stack id. - Add it to `Environment.pipeline` in the canonical order: `clone → state → checkoutMerged → dockerSwarmCheck → build → deploy → optionals`. Build and deploy are explicit `DockerComposeBuild` and `DockerSwarmDeploy` siblings; do not collapse them into one step. If you skip the `GitUnmerge` line, `state.branches` will stay empty and the stack will only deploy when an operator pushes a `branches` update through the UI. Don't skip it; it's the difference between a self-driving stack and a manual one. See `connectivity_tester.py` history for the bug this caused. ## Verification checklist - `python3 -c "from backend.configs.my_stack import my_stack"` works in the brencher container. - `PROFILES="my_stack" python3 backend/app.py` boots and the UI renders a row for `my_stack` with non-empty branches (from `GitUnmerge`, pointing at whatever image is currently deployed). - Push to the configured branch, wait one full polling cycle (~`RESET_INTERVAL` = 180s, plus the next pipeline tick), then confirm the service was redeployed with a new `org.brencher.version` label. - No UI `environment_update` was issued in between. ## Common foot-guns - `dockerfile:` path in `stack-compose.yml` is interpreted relative to the compose file's directory. The compose file and the Dockerfile must live side-by-side; use `dockerfile: Dockerfile`, not `dockerfile: `. - Removing the `name:` key from the top of `stack-compose.yml` is fine for `docker stack deploy` — the stack name comes from the CLI option brencher sets. - `EXTRA_ENDPOINTS` and friends are env vars; if you reference them in compose, define them in the `envs=lambda: {...}` of the `DockerComposeBuild` and `DockerSwarmDeploy`. `substitute` uses `env.get(...)` for deploys but `env[...]` (raises) for builds, so an unlisted variable kills the build but quietly produces an empty string in the deploy. - Compose files must not assume Docker networks that don't exist. Use either an `external: true` net that already exists in Swarm, drop the `networks:` block entirely, or `driver: overlay` for a stack-private net. ## Tracking When you add a stack, also: - Open a tracking issue in `admin/brencher` titled `[ready-to-test] : …` with `state=` from your `GitUnmerge`-derived branches and what URL/port the service exposes. - Add the stack id to the `PROFILES` env var in the brencher stack compose (`docker_stack` / Swarm declarative) so it gets picked up on next rollout. The admin overlay is where this lives. ## Build delegation pattern (Actions) Brencher does not run docker build or docker push itself. It dispatches a Gitea Actions workflow via `POST /api/v1/repos/{owner}/{repo}/actions/workflows/{file}/dispatches`, waits for the run to complete, then runs `docker stack deploy`. Use `steps.actions.GiteaActionsTrigger` and `steps.actions.GiteaActionsAwait` in the stack config, set `buildDocker=None` on `DockerSwarmDeploy`, and let Swarm resolve and pull the image on target nodes during deploy. Credentials must be available to the deploy path and the compose image must point to a registry the runner can push to (e.g. Gitea Container Registry `gitea.rudolf.keenetic.link//`).