feat(infra): add ci-runners.sh wrapper for the runner stack
Mirrors the convenience-script pattern we adopted for
infra/local/dev.sh: typing
`docker compose -f infra/ci-runners.compose.yml ...` for routine
ops (status, restart, log tail) gets old fast, the pre-pull of
the catthehacker job images is documented but easy to forget,
and the "rotation of one runner at a time" tip in
infra/README.md is a sequence the contributor was supposed to
hand-roll every time.
`infra/ci-runners.sh` exposes:
./ci-runners.sh up # bring up runner-1..3
./ci-runners.sh up --prepull # pre-pull job images first
./ci-runners.sh down # stop + remove (preserves
data/runner-N/.runner creds)
./ci-runners.sh restart <runner> # restart one runner
./ci-runners.sh rotate # rolling restart with a 15 s
pause between each — keeps
at least N-1 runners online
through a config refresh
./ci-runners.sh status # docker compose ps
./ci-runners.sh logs [runner] # follow logs
./ci-runners.sh pull-images # idempotent image refresh
Anything else is passed through to
`docker compose -f ci-runners.compose.yml ...`. The destructive
`down -v` (wipes data/, forces re-registration with a fresh
Gitea token) is intentionally NOT exposed as a verb — invoke
docker compose directly so the path is explicit at the typing
level.
`infra/README.md` updated:
- Inventory table at the top picks up the script.
- "First-time registration" walkthrough swaps the explicit
docker pull / docker compose up steps for `./ci-runners.sh
up --prepull`.
- New "Convenience script — ci-runners.sh" subsection with the
cheat-sheet table.
- "Operational tips" rephrased to point at the script's `rotate`
/ `restart` / `logs` verbs as the canonical commands; the
raw-docker-compose form is kept in parentheses as the
underlying mechanism.
- "Adding a fourth runner" tip now reminds to update the
RUNNERS=() array at the top of the script.
The 15 s pause in `rotate` is a conservative approximation —
act_runner doesn't expose a Compose healthcheck, so we can't
poll for ready. Adjust the constant if reality argues for a
different value.
Smoke-tested help + arg-validation paths on the host.
This commit is contained in:
Julien Gautier
+33
-13
@@ -6,6 +6,7 @@ Infrastructure-as-code artefacts for the project. Separate from application code
|
||||
| -------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Self-hosted CI runners (Gitea Actions) | [`ci-runners.compose.yml`](ci-runners.compose.yml) | [ADR-0015 §"Runners"](../docs/decisions/0015-cicd-gitea-actions.md) |
|
||||
| Shared `act_runner` configuration | [`runner-config.yaml`](runner-config.yaml) | [ADR-0015 §"Runners"](../docs/decisions/0015-cicd-gitea-actions.md) |
|
||||
| CI runners convenience script | [`ci-runners.sh`](ci-runners.sh) | See "Convenience script" below |
|
||||
| Runtime state of the runners | `data/` (git-ignored after `.gitignore`) | — |
|
||||
| Env-vars template for the runners | `.env.example` (`.env` is git-ignored) | — |
|
||||
| Local-dev runtime stack | [`local/`](local/) | [ADR-0006](../docs/decisions/0006-persistence-postgresql-prisma.md), [ADR-0010](../docs/decisions/0010-session-management-redis.md), [ADR-0012](../docs/decisions/0012-observability-pino-opentelemetry.md), [ADR-0013](../docs/decisions/0013-audit-trail-separated-postgres-append-only.md) |
|
||||
@@ -36,28 +37,47 @@ $EDITOR .env
|
||||
# Set GITEA_INSTANCE_URL (https, no trailing slash) and
|
||||
# GITEA_RUNNER_REGISTRATION_TOKEN.
|
||||
|
||||
# 3. Pre-pull the job images so the runner doesn't have to (see
|
||||
# "Job image pinning and pre-pull" below for the rationale).
|
||||
docker pull catthehacker/ubuntu:act-22.04
|
||||
docker pull catthehacker/ubuntu:full-22.04
|
||||
# 3. Pre-pull the job images and bring the runners up. The script
|
||||
# chains the two — see "Job image pinning and pre-pull" below
|
||||
# for the rationale.
|
||||
./ci-runners.sh up --prepull
|
||||
|
||||
# 4. Bring the runners up.
|
||||
docker compose -f ci-runners.compose.yml up -d
|
||||
|
||||
# 5. Verify in Gitea: the three runners appear as online with the
|
||||
# 4. Verify in Gitea: the three runners appear as online with the
|
||||
# self-hosted, on-prem labels. If a runner doesn't come online,
|
||||
# inspect its logs:
|
||||
docker compose -f ci-runners.compose.yml logs runner-1
|
||||
./ci-runners.sh logs runner-1
|
||||
```
|
||||
|
||||
After the first successful boot, each runner stores its credentials under `data/runner-N/.runner`. The registration token is no longer needed and **should be removed** from `.env`. Subsequent restarts (`docker compose restart`) authenticate from the persisted credential.
|
||||
After the first successful boot, each runner stores its credentials under `data/runner-N/.runner`. The registration token is no longer needed and **should be removed** from `.env`. Subsequent restarts (`./ci-runners.sh restart …` or direct `docker compose restart …`) authenticate from the persisted credential.
|
||||
|
||||
### Convenience script — `ci-runners.sh`
|
||||
|
||||
[`ci-runners.sh`](ci-runners.sh) is a thin wrapper around `docker compose -f ci-runners.compose.yml ...` for the everyday verbs. Two reasons to use it:
|
||||
|
||||
1. **Hides the compose-file path** on every command. `./ci-runners.sh up` instead of `docker compose -f ci-runners.compose.yml up -d`.
|
||||
2. **`rotate` automates the rolling restart** the "Operational tips" below recommend: runner-1 → wait → runner-2 → wait → runner-3, so the CI pipeline always has at least N-1 runners online while you push a config change.
|
||||
|
||||
| Command | Effect |
|
||||
| ---------------------------------- | ------------------------------------------------------------------------------ |
|
||||
| `./ci-runners.sh up` | Bring the three runner containers up |
|
||||
| `./ci-runners.sh up --prepull` | Pre-pull the job images (`act-22.04` + `:full-22.04`) on the host first |
|
||||
| `./ci-runners.sh down` | Stop and remove the containers (preserves `data/runner-N/.runner` credentials) |
|
||||
| `./ci-runners.sh restart <runner>` | Restart one runner |
|
||||
| `./ci-runners.sh rotate` | Rolling restart of every runner with a 15 s pause between each |
|
||||
| `./ci-runners.sh status` | `docker compose ps` for the runner services |
|
||||
| `./ci-runners.sh logs [runner]` | Follow logs (one runner or all of them) |
|
||||
| `./ci-runners.sh pull-images` | Pre-pull / refresh the job images (idempotent) |
|
||||
|
||||
Anything not matching one of the named verbs is passed through to `docker compose -f ci-runners.compose.yml ...`. Run `./ci-runners.sh help` for the full reference.
|
||||
|
||||
For the destructive `down -v` (wipes `data/`, forces re-registration with a fresh Gitea token), the script intentionally **doesn't** offer a verb — invoke `docker compose -f ci-runners.compose.yml down -v` directly so the path is explicit at the typing level.
|
||||
|
||||
### Operational tips
|
||||
|
||||
- **Rotation of one runner at a time** — to upgrade the image or change config, restart runners one by one (`docker compose restart runner-1`, wait, runner-2, …) so the CI pipeline is never starved.
|
||||
- **Logs** — `docker compose logs -f --tail=100 runner-N` for a single runner; jobs being executed appear here.
|
||||
- **Rotation of one runner at a time** — to upgrade the image or change config, run `./ci-runners.sh rotate` (or restart manually one by one — `./ci-runners.sh restart runner-1`, wait, …) so the CI pipeline is never starved.
|
||||
- **Logs** — `./ci-runners.sh logs runner-N` (or `docker compose logs -f --tail=100 runner-N`) for a single runner; jobs being executed appear here.
|
||||
- **Disk pressure** — the runner caches each job's container image in `/var/lib/docker` on the host. On a small host, prune periodically (`docker system prune -af` while no job is running).
|
||||
- **Adding a fourth runner** — copy any `runner-N` block in the compose file, increment the suffix in `container_name`, `GITEA_RUNNER_NAME`, and the `data/` mount path. Then `docker compose up -d`. The runner registers using the same `GITEA_RUNNER_REGISTRATION_TOKEN` (which must be regenerated if it has expired).
|
||||
- **Adding a fourth runner** — copy any `runner-N` block in the compose file, increment the suffix in `container_name`, `GITEA_RUNNER_NAME`, and the `data/` mount path. Add the new name to the `RUNNERS=(…)` array at the top of `ci-runners.sh` so `rotate` and `restart` learn about it. Then `./ci-runners.sh up` (or `docker compose up -d`). The runner registers using the same `GITEA_RUNNER_REGISTRATION_TOKEN` (which must be regenerated if it has expired).
|
||||
|
||||
### Security — Docker socket exposure
|
||||
|
||||
|
||||
Reference in New Issue
Block a user