## 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>
112 lines
5.4 KiB
Markdown
112 lines
5.4 KiB
Markdown
# 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>`).
|