Julien Gautier
308f505f38
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.
Documentation index
This is the entry point to all project documentation. It is maintained automatically: any addition, rename, or removal of a .md file under docs/ must be reflected here in the same change.
Conventions
- Documentation is written in English.
- One topic per file. Group related files into a folder when there are three or more.
- Cross-reference with relative links so they keep working in GitHub, IDEs, and exported sites.
- For architectural decisions, do not add them here — they belong in decisions/ as MADR 4.0.0 ADRs.
Sections
Daily development
- development.md — repo layout, prerequisites, initial setup, daily commands, observability dev-loop (Jaeger UI, log ↔ trace correlation), dependency updates (Renovate), conventional commit cycle. Day-to-day reference for working on the project.
Architecture
- architecture.md — cross-cutting Mermaid diagrams: C4 system context, C4 containers, Nx module boundaries, CI/CD pipeline. Single-decision diagrams (auth sequence, ERD, etc.) live inline in their ADR.
Onboarding & environment
Setup guides for new contributors:
- setup/01-wsl-terminal-setup.md — modern WSL terminal (Zsh + Powerlevel10k + CLI tools)
- setup/02-dev-web-stack.md — Node via nvm, pnpm via corepack, Docker
- setup/03-angular-nx-monorepo.md — Angular + Nx monorepo bootstrap
Operations & runbooks
Empty — to be populated when we deploy.
Security, performance, accessibility
Empty — placeholders to be filled with rationale docs alongside their corresponding ADRs.