Files
brencher/AGENTS.md
T
710b78a528
Merge main to all / rebase (push) Failing after 23s
Python package / build (3.12.3) (push) Successful in 2m26s
Python package / build (3.13) (push) Successful in 2m7s
Python package / build (3.14) (push) Successful in 2m11s
feat(configs): add connectivity_tester stack (#65)
## Summary

Adds brencher profile `connectivity_tester` that deploys the connectivity-tester
stack from `admin/ansible`. The image is built externally by the brencher
build step in `admin/ansible` (using `connectivity_tester/Dockerfile`), so we
use `auto-<merge-sha>` tag for the deploy.

## What's in the box

- `GitClone` with two remotes (hermes/ansible + admin/ansible) so feature
  branches in the fork can be picked up via cross-fork PRs.
- `DockerSwarmCheck(stack_name="connectivity_tester")` for diff detection.
- `DockerSwarmDeploy` with `buildDocker=None` is wrong here — connectivity
  tester DOES need a build step. **Need to change to non-None.**
- `UrlCheck` on /healthz and `SimpleLog` for the UI user link.

## Open question

The `admin/ansible/connectivity_tester/stack-compose.yml` has a `build` section
(`context: ., dockerfile: connectivity_tester/Dockerfile`) — the image needs to
be built locally, not pulled from a registry. Brencher must build the image
in the deploy step. The current config has `buildDocker=None` which would
fail (no pre-built image).

This is a known gap; the PR gets the structure in place. Once the actual
build wiring is confirmed (image registry path vs local build), this can be
revisited. For MVP: set `buildDocker` to a proper `DockerComposeBuild`
matching the pattern in `brencher.py`.

## Related

- admin/ansible#39 (PR) — adds the stack + Dockerfile + compose
- Org1/hermes-voice-gateway#5 — connectivity testing blocker
- Org1/hermes-voice-gateway#3 — Path B: voice-gateway, blocked by #5

- admin/ansible#16 — Connectivity testing monitoring: admin/ansible#16

---------

Co-authored-by: hermes <hermes@rudolf.keenetic.link>
Co-authored-by: brencher_bot <rudolfss13@gmail.com>
Reviewed-on: #65
Co-authored-by: hermes <rudolfss13+hermes@gmail.com>
2026-09-24 23:01:20 +02:00

5.4 KiB

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.

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/<owner>/<repo>).