docs(brencher): add AGENTS.md checklist for new stacks
This commit is contained in:
@@ -0,0 +1,99 @@
|
||||
# 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/<stack>.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="<stack>")` 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-<short-sha>` 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: <relative-path>`.
|
||||
- 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] <stack>: …` 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.
|
||||
Reference in New Issue
Block a user