## 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: admin/brencher#65 Co-authored-by: hermes <rudolfss13+hermes@gmail.com>
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:
- Push branch
feat/my_stack(or whatever the team convention is) to a Git repo listed inremotesof the config file. - Drop the repo in
giteaorgithubso it's reachable through the same remotes that other stacks use. - Make sure
my_stack/stack-compose.ymland a Dockerfile (typicallymy_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
GitClonewith at least one remote whoseurlpoints to the repo above. - Build a
DockerSwarmCheck(stack_name="<stack>")to introspect the deployed service. - Build
GitUnmerge(clone, dockerSwarmCheck)and wrap it intoSharedStateHolderInMemory(unmerge=unmerge). This is what makes autodeploy work —GitUnmergereads theorg.brencher.versionlabel from the running swarm task and converts it intodesired_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 staysFalsefor first-party stacks; setTrueonly when you want brencher to push auto-named branches back to origin. - Build a
DockerComposeBuild(orDockerSwarmBuildif a Swarmfile is used) pointing at the compose path in the repo. - Build a
DockerSwarmDeploy(wd=clone, buildDocker=…, stackChecker=…, …)with the samestack_name. Image tag isauto-<short-sha>driven bycheckoutMerged.progress().version. - Optionally append a
SimpleLog(message={"userLinks": {...}})for the link to surface in the UI. - Set
__all__and export theEnvironmentnamed after the stack id. - Add it to
Environment.pipelinein the canonical order:clone → state → checkoutMerged → dockerSwarmCheck → build → deploy → optionals. Build and deploy are explicitDockerComposeBuildandDockerSwarmDeploysiblings; 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.pyboots and the UI renders a row formy_stackwith non-empty branches (fromGitUnmerge, 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 neworg.brencher.versionlabel. - No UI
environment_updatewas issued in between.
Common foot-guns
dockerfile:path instack-compose.ymlis interpreted relative to the compose file's directory. The compose file and the Dockerfile must live side-by-side; usedockerfile: Dockerfile, notdockerfile: <relative-path>.- Removing the
name:key from the top ofstack-compose.ymlis fine fordocker stack deploy— the stack name comes from the CLI option brencher sets. EXTRA_ENDPOINTSand friends are env vars; if you reference them in compose, define them in theenvs=lambda: {...}of theDockerComposeBuildandDockerSwarmDeploy.substituteusesenv.get(...)for deploys butenv[...](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: truenet that already exists in Swarm, drop thenetworks:block entirely, ordriver: overlayfor a stack-private net.
Tracking
When you add a stack, also:
- Open a tracking issue in
admin/brenchertitled[ready-to-test] <stack>: …withstate=from yourGitUnmerge-derived branches and what URL/port the service exposes. - Add the stack id to the
PROFILESenv 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>).