Julien Gautier
644d3603d2
Set up the infrastructure-as-code recipe to bring up the three
self-hosted Gitea Actions runners required by ADR-0015. The compose
file launches three act_runner instances pinned to 0.2.13, registered
with the project's Gitea organisation, labelled self-hosted + on-prem
to match the runs-on selector in every job under .gitea/workflows/*.
Layout:
- infra/ new top-level folder for IaC
- infra/README.md explains the folder, registration
flow, security implications, future
placeholders (local/, prod/, runbooks/)
- infra/ci-runners.compose.yml three act_runner services, networked
together, persisting credentials to
./data/runner-N
- infra/.env.example GITEA_INSTANCE_URL +
GITEA_RUNNER_REGISTRATION_TOKEN; .env
itself stays git-ignored (root rule)
- infra/data/.gitignore tracks the dir, ignores runtime state
Security posture (documented in infra/README.md): mounting
/var/run/docker.sock gives the runner root-equivalent access to the
host Docker daemon. Mitigations rely on (a) repo-scope of the runner
in Gitea, (b) running the runner host outside the production trust
boundary, (c) no extra host filesystem mounts. Future hardening
(rootless Docker, DinD sidecar) is flagged as deferred.
The compose pins the runner image (0.2.13). Bumps go through a
dedicated chore(deps) PR per the convention; image upgrades roll one
runner at a time so CI is never starved (procedure documented in the
README).
Doc indexing (docs/README.md) deliberately not touched here to avoid
a conflict with the pending docs/architecture-diagrams branch which
also modifies that file. A small follow-up PR will add an index entry
once that branch is merged.
88 lines
7.2 KiB
Markdown
88 lines
7.2 KiB
Markdown
# `infra/`
|
|
|
|
Infrastructure-as-code artefacts for the project. Separate from application code and from documentation: this folder contains the recipes and configs that the team and ops use to stand up running infrastructure (CI runners, future local-dev databases, future on-prem deploy assets).
|
|
|
|
| Subject | File / Folder | ADR / Reference |
|
|
| -------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------- |
|
|
| Self-hosted CI runners (Gitea Actions) | [`ci-runners.compose.yml`](ci-runners.compose.yml) | [ADR-0015 §"Runners"](../docs/decisions/0015-cicd-gitea-actions.md) |
|
|
| Runtime state of the runners | `data/` (git-ignored after `.gitignore`) | — |
|
|
| Env-vars template for the runners | `.env.example` (`.env` is git-ignored) | — |
|
|
|
|
Future folders / files that will land here as the corresponding ADRs ship:
|
|
|
|
- **`local/`** — Docker Compose for the developer's machine (Postgres + Redis + OTel collector). Triggered by the first feature that needs Redis (sessions, ADR-0010).
|
|
- **`prod/`** — On-prem deploy manifests (HA Postgres, Redis Sentinel, OTel collector + backend, secret manager). Triggered by the on-prem infrastructure ADR (phase 3b).
|
|
|
|
---
|
|
|
|
## CI runners — `ci-runners.compose.yml`
|
|
|
|
Three self-hosted [`act_runner`](https://gitea.com/gitea/act_runner) instances, registered with the project's Gitea organisation, labelled `self-hosted` + `on-prem` (the labels referenced by every job in `.gitea/workflows/*`). Three matches the floor recommended by [ADR-0015 §"Runners"](../docs/decisions/0015-cicd-gitea-actions.md) — one runner is enough to validate the pipeline; two leave no slack; three keep CI flowing if one runner is down for upgrade or maintenance.
|
|
|
|
### First-time registration
|
|
|
|
```bash
|
|
cd infra/
|
|
|
|
# 1. Generate a registration token in Gitea.
|
|
# Site Administration → Actions → Runners → "Create new Runner"
|
|
# (or, for org-scoped runners: Organisation Settings → Actions → Runners).
|
|
# The token is one-time and short-lived; don't lose it.
|
|
|
|
# 2. Configure .env (which is git-ignored).
|
|
cp .env.example .env
|
|
$EDITOR .env
|
|
# Set GITEA_INSTANCE_URL (https, no trailing slash) and
|
|
# GITEA_RUNNER_REGISTRATION_TOKEN.
|
|
|
|
# 3. Bring the runners up.
|
|
docker compose -f ci-runners.compose.yml up -d
|
|
|
|
# 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
|
|
```
|
|
|
|
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.
|
|
|
|
### 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.
|
|
- **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).
|
|
|
|
### Security — Docker socket exposure
|
|
|
|
The compose mounts `/var/run/docker.sock` into each runner so jobs can spawn containers. **This grants the runner root-equivalent access to the host's Docker daemon.** A malicious workflow could spawn arbitrary containers, mount host paths, escalate privileges. Mitigations:
|
|
|
|
- **Trust boundary:** only register the runners against repositories controlled by the org. Gitea's runner-registration UI lets you scope a runner to an organisation, a single repository, or instance-wide. Prefer the narrowest scope.
|
|
- **Dedicated host:** run these containers on a host that does not also run production services or hold sensitive data. The runner host is in the trust boundary of any developer who can push to a repo it serves.
|
|
- **No host filesystem mounts beyond the docker socket:** the compose intentionally does not mount `/`, `/etc`, or any project source. Workflows that need data on the host must do so via Docker volumes.
|
|
- **Future hardening (out of scope of v1):** migrate to **rootless Docker** on the runner host, or to a **DinD (Docker-in-Docker) sidecar** so the runner cannot escape into the host daemon. Decided when the org's RSSI confirms the security posture, or when the runner host is shared with anything else of value.
|
|
|
|
### Image pinning
|
|
|
|
The compose pins `gitea/act_runner:0.2.13`. Update the pin deliberately, not via `:latest`:
|
|
|
|
1. Read the act_runner [release notes](https://gitea.com/gitea/act_runner/releases) for breaking changes.
|
|
2. Edit the three image references (`runner-1`, `runner-2`, `runner-3`).
|
|
3. Commit on a feature branch with a `chore(deps):` Conventional Commits subject.
|
|
4. Roll one runner at a time (rotation tip above).
|
|
|
|
The matching CI workflows refer to runner _labels_ (not images), so a runner-image upgrade does not affect `.gitea/workflows/*`.
|
|
|
|
---
|
|
|
|
## Future infra concerns — placeholders
|
|
|
|
These are listed here so a contributor knows where to expect related files; they don't exist yet.
|
|
|
|
| File | Purpose | Triggered by |
|
|
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
|
|
| `local/dev.compose.yml` | Postgres 17 + Redis (Sentinel-flavoured single-node) + OTel collector for local dev | First feature that needs Redis or end-to-end OTel traces |
|
|
| `local/init/postgres/*.sql` | Bootstrap SQL to create the Postgres roles `audit_owner` / `audit_writer` / `audit_reader` / `audit_archiver` (per ADR-0013) and provision the dev DB | Same as above |
|
|
| `prod/*` | On-prem deployment manifests (k8s, Compose, or whatever the on-prem infra ADR settles on) | The on-prem infrastructure ADR (phase 3b) |
|
|
| `runbooks/*.md` | Operational runbooks (incident response, secret rotation, runner upgrade procedure, …) | First incident, or when ops cadence justifies them |
|