docs: refresh stale documentation to match ansible/opentofu/production #31

Sammanfogat

supernaut sammanfogade 1 incheckning från docs/refresh-staleness in i main

2026-07-09 15:16:59 +00:00

supernaut kommenterad

2026-07-09 15:12:23 +00:00

Ägare

Summary

Audited all documentation in bitborg-infra against the actual ansible/, opentofu/, and live production, and corrected the drift that had accumulated (ADRs 0021–0024, the dedicated backup volume, ephemeral runners, self-hosted Renovate, state encryption, off-site backups). Verification was done with four parallel read-only audit passes cross-checked against code, plus live Prometheus checks (Renovate + runner-controller metrics confirm both are running; backup volume confirmed 100 GB).

Mermaid diagrams (8 total, all re-verified)

architecture.md backups diagram: cipher AES-256 → age / ChaCha20-Poly1305 (it contradicted its own prose).
architecture.md + README.md main diagrams: added renovate (+ registry-mirror in architecture.md) nodes and edges (ADR 0023); off-site node relabelled Bahnhof S3 → Hetzner S3 (hel1, interim EU) and the edge marked enabled (was "optional/off by default"); backup node annotated as the dedicated /srv/gitborg-backup volume.

Prose / factual corrections

File	Fix
`CLAUDE.md`	ADR range `0001–0021` → `0001–0024`; roles list +`renovate`,`registry-mirror` (14); note `encryption.tofu` + encrypted state; backup off-site Bahnhof → Hetzner (enabled)
`README.md`	backup description → dedicated volume (ADR 0022) + Hetzner off-site; renovate in diagram; "at a glance" rows for ADR 0022/0023/0024
`opentofu/README.md`	`.tf` → `.tofu`; added `encryption`/`monitoring`/`ephemeral-runners` files; documented the now-mandatory `TF_VAR_state_encryption_passphrase` step
`docs/runbook.md`	`runner_controller_dry_run` ships `false` not `true` (rollout text corrected); added the online backup-volume grow procedure (was missing) + current 100 GB size
`docs/design/forgejo-actions-runners.md`	superseded banner → ADR 0021; fixed refs to nonexistent `runner.tofu`/`roles/runner`; pool label `gitborg-shared` → `ci`
`docs/design/monitoring.md`	Loki retention `15 d` → `7 d` (matches privacy policy)
`docs/roadmap.md`	off-site backup already shipped (Hetzner interim) — reframed remaining work
`README-runner-image.md`	runner `v12.8` → `v12.12.0`; Debian 12 → 13; dropped retired standing runner VM; download host `data.` → `code.forgejo.org`
`docs/bahnhof-vpc.md`	`ceph-nvme` price `1` → `5` SEK/GB (matches `cost/prices.yml` + its own table)
`docs/decisions/0012`	added "partially superseded by ADR 0014" status pointer (respecting ADR immutability)

Follow-up flagged (NOT in this PR — it's a code issue, not a doc issue)

roles/runner-controller/defaults/main.yml sets runner_controller_dry_run: false, but the role's own code comments (defaults, controller.py, container template) all say "default is true". So a fresh --tags runner-controller apply runs live (boots/reaps real VMs) contrary to the comments' intent. This PR fixes the docs to match reality; the code default + contradictory comments should be reconciled separately (likely flip the default back to true).

## Summary Audited **all** documentation in `bitborg-infra` against the actual `ansible/`, `opentofu/`, and live production, and corrected the drift that had accumulated (ADRs 0021–0024, the dedicated backup volume, ephemeral runners, self-hosted Renovate, state encryption, off-site backups). Verification was done with four parallel read-only audit passes cross-checked against code, plus live Prometheus checks (Renovate + runner-controller metrics confirm both are running; backup volume confirmed 100 GB). ## Mermaid diagrams (8 total, all re-verified) - **architecture.md backups diagram**: cipher `AES-256` → **age / ChaCha20-Poly1305** (it contradicted its own prose). - **architecture.md + README.md main diagrams**: added **renovate** (+ **registry-mirror** in architecture.md) nodes and edges (ADR 0023); off-site node relabelled **Bahnhof S3 → Hetzner S3 (hel1, interim EU)** and the edge marked enabled (was "optional/off by default"); backup node annotated as the dedicated `/srv/gitborg-backup` volume. ## Prose / factual corrections | File | Fix | | ---- | --- | | `CLAUDE.md` | ADR range `0001–0021` → `0001–0024`; roles list +`renovate`,`registry-mirror` (14); note `encryption.tofu` + encrypted state; backup off-site Bahnhof → Hetzner (enabled) | | `README.md` | backup description → dedicated volume (ADR 0022) + Hetzner off-site; renovate in diagram; "at a glance" rows for ADR 0022/0023/0024 | | `opentofu/README.md` | `.tf` → `.tofu`; added `encryption`/`monitoring`/`ephemeral-runners` files; documented the now-mandatory `TF_VAR_state_encryption_passphrase` step | | `docs/runbook.md` | `runner_controller_dry_run` ships **`false`** not `true` (rollout text corrected); **added the online backup-volume grow procedure** (was missing) + current 100 GB size | | `docs/design/forgejo-actions-runners.md` | superseded banner → ADR 0021; fixed refs to nonexistent `runner.tofu`/`roles/runner`; pool label `gitborg-shared` → `ci` | | `docs/design/monitoring.md` | Loki retention `15 d` → `7 d` (matches privacy policy) | | `docs/roadmap.md` | off-site backup already shipped (Hetzner interim) — reframed remaining work | | `README-runner-image.md` | runner `v12.8` → `v12.12.0`; Debian 12 → 13; dropped retired standing runner VM; download host `data.` → `code.forgejo.org` | | `docs/bahnhof-vpc.md` | `ceph-nvme` price `1` → `5` SEK/GB (matches `cost/prices.yml` + its own table) | | `docs/decisions/0012` | added "partially superseded by ADR 0014" status pointer (respecting ADR immutability) | ## Follow-up flagged (NOT in this PR — it's a code issue, not a doc issue) `roles/runner-controller/defaults/main.yml` sets `runner_controller_dry_run: false`, but the role's own code comments (defaults, `controller.py`, container template) all say "default is true". So a fresh `--tags runner-controller` apply runs **live** (boots/reaps real VMs) contrary to the comments' intent. This PR fixes the *docs* to match reality; the code default + contradictory comments should be reconciled separately (likely flip the default back to `true`).

supernaut lade till 1 incheckning

2026-07-09 15:12:23 +00:00

docs: refresh stale documentation to match ansible/opentofu/production 7b37132307

Audited all docs against current code + live prod. Fixes:

- architecture.md: backups diagram cipher AES-256 → age/ChaCha20-Poly1305;
  add renovate + registry-mirror nodes (ADR 0023); S3 node Bahnhof → Hetzner
  hel1 (interim, enabled); annotate dedicated backup volume; add gitborg-web
  OIDC client; new 'Dependency updates' component section.
- README.md: same backup/S3 correction + dedicated volume (ADR 0022); add
  renovate to the mermaid + 'at a glance' rows for backups/renovate/service
  accounts (0022/0023/0024).
- CLAUDE.md: ADR range 0001-0021 → 0001-0024; roles list add renovate +
  registry-mirror (14 roles); note encryption.tofu + encrypted state; backup
  off-site Bahnhof → Hetzner (enabled).
- opentofu/README.md: .tf → .tofu; add encryption/monitoring/ephemeral-runners
  files; document mandatory TF_VAR_state_encryption_passphrase step.
- runbook.md: correct runner_controller_dry_run (ships false, not true); add
  online backup-volume grow procedure (missing) + current 100 GB size.
- design/forgejo-actions-runners.md: superseded banner → ADR 0021 (ephemeral);
  fix nonexistent runner.tofu/roles/runner refs and pool label (ci).
- design/monitoring.md: Loki retention 15 d → 7 d (matches privacy policy).
- roadmap.md: off-site backup shipped (Hetzner interim), reframe remaining work.
- README-runner-image.md: runner v12.8 → v12.12.0; Debian 12 → 13; drop retired
  runner VM; download host data.forgejo.org → code.forgejo.org.
- bahnhof-vpc.md: ceph-nvme price 1 → 5 SEK/GB (matches cost/prices.yml).
- ADR 0012: add 'partially superseded by ADR 0014' status pointer.

supernaut sammanfogade incheckning 62aafeb2f0 till main

2026-07-09 15:16:59 +00:00

supernaut tog bort grenen docs/refresh-staleness

2026-07-09 15:16:59 +00:00

supernaut refererade denna ändringsförfrågan från en incheckning

2026-07-09 15:17:01 +00:00

docs: refresh stale documentation to match ansible/opentofu/production (#31)

supernaut refererade till denna ändringsförfrågan

2026-07-09 15:24:47 +00:00

fix(runner-controller): safe dry_run default (true), opt prod in via group_vars #32

supernaut refererade denna ändringsförfrågan från en incheckning

2026-07-09 15:28:29 +00:00