forgejo-runner: give CI jobs a Docker daemon of their own

jar-lid-archive's CI needs `docker build` and `docker compose`, and job
containers had no Docker at all: config.yml carried the stock
`container.docker_host: "-"`, which is precisely "find a daemon for the
runner and do not let jobs near it".

A docker:dind sidecar now runs on forgejo-runner-box, published on
127.0.0.1 only, and jobs build against that instead of the host daemon.
Following Forgejo's own admin docs, which make the point that this is
THREE settings and not one:

  forgejo-dind.service        a privileged docker:dind on the host daemon
  container.docker_host       tcp://127.0.0.1:2376 - where the runner
                              CREATES job containers
  runner.envs.DOCKER_HOST +   tcp://forgejo-dind.docker.internal:2375 -
  container.options           how a job, from INSIDE dind, reaches it

The third is the one that is easy to miss and fails identically to
having done nothing: for a tcp:// docker_host the runner mounts nothing
into the job container, so the job still finds no daemon. The two
addresses differ because they are used from different places - the
runner is a process on the host; a job container is inside dind, where
127.0.0.1 is itself. `host-gateway` is expanded by the daemon creating
the container, which is dind, so it lands on dind's own bridge gateway.

Verified on the box, along the exact path a job takes - a container on a
user-defined network, with the same --add-host and DOCKER_HOST the
runner will set: the name resolves to 172.20.0.1, `docker version`
returns the dind server, and `docker build` succeeds. The host daemon
runs forgejo-dind and nothing else.

config.yml had to become a template to do any of this. It was previously
`generate-config` run once on first deploy and never touched again, so
the repo had no say in its contents. Every value was transcribed from
the live file and diffed against it key by key: with dind disabled, 30
of 30 identical. Two deliberate differences - runner.envs drops
A_TEST_ENV_NAME_1/2, upstream's placeholders, which were being injected
into every job here; and the upstream comment blob is gone. Because the
file is managed now it also gets a restart handler, the absence of which
has bitten this repo before.

Things deliberately chosen rather than defaulted into:

- the flag lives in the playbook, not the role defaults, so the role's
  default stays the configuration this host has always run and turning
  it off is one line. Disabling it also tears the units down rather than
  just skipping them.
- dind is a hard Requires= of forgejo-runner, and its unit stays in
  "activating" until the daemon answers. A dead dind is then one red
  unit instead of a green runner failing every job it claims.
- the healthcheck and monitored_services learned about dind for the same
  reason: runner up + dind down is the interesting failure and it was
  previously invisible.
- /var/lib/docker is a named volume, or every image is re-pulled on each
  container recreation; a weekly prune keeps that from growing forever.
- dind's network pool is pinned to 172.20.0.0/14. Docker's stock pool
  reaches into 192.168.x, and act_runner creates a network per job, so a
  job could eventually allocate this LAN's subnet and lose the route to
  every box on it.

Note this runner is SHARED - arbret, arbret-biz, arbretdos and
arbret-ops build here too, far more often, and docker_host is per-runner
not per-repo. Their workflows are unchanged but their next run pulls
images into a cold cache. Job images still need a docker client of their
own: node:{20,22}-bookworm ship none.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

ansible/roles/forgejo_runner/README.md

@@ -57,3 +57,100 @@ never ran. It is not a monitoring task — it is the deployment checking its own
 work — and the deprecation banner swept it up by mistake. It is ungated here,
 which means a runner that fails to start now fails the play instead of
 deploying "successfully" in silence.
+
+## Docker-in-Docker for jobs
+
+`forgejo_runner_dind_enabled: true` gives Actions jobs a Docker daemon of their
+own — a `docker:dind` container on this host's daemon, isolated from it — so
+`docker build` and `docker compose` work inside a workflow.
+
+It follows Forgejo's own [Utilizing Docker within
+Actions](https://forgejo.org/docs/latest/admin/actions/docker-access/) →
+Docker-in-Docker, which is **three** parts, not one:
+
+| | what it does | where it applies |
+|---|---|---|
+| `forgejo-dind.service` | a `docker:dind` container, published on `127.0.0.1:2376` only | the host |
+| `container.docker_host` | `tcp://127.0.0.1:2376` — the runner creates job/service/step containers **on dind** | the runner process |
+| `runner.envs.DOCKER_HOST` + `container.options` | `tcp://forgejo-dind.docker.internal:2375`, resolved by `--add-host=…:host-gateway` | inside each job container |
+
+The third row is the one that is easy to miss, and leaving it out fails in a
+way that looks identical to not having configured anything. `docker_host` only
+decides **where the job container is created**; for a `tcp://` value Forgejo
+mounts nothing into that container, so the job still has no daemon. The two
+addresses differ because they are used from different places — the runner is a
+process on the host and reaches dind on loopback; a job container is *inside*
+dind, where `127.0.0.1` is itself. `host-gateway` is expanded by the daemon
+that creates the container, which is dind, so it lands on dind's own bridge
+gateway where its `dockerd` is listening.
+
+### What changes for jobs
+
+- Job containers, service containers and anything a job starts all live on the
+  dind daemon. A `postgres` service and a `docker compose` stack are siblings
+  there, so they reach each other by name — which is what makes end-to-end
+  tests work.
+- **Nothing a workflow does can touch this host's Docker daemon any more.**
+  That is the point of dind over `automount`.
+- dind has its own image store. Every image is pulled again the first time it
+  is needed. It is a named volume (`forgejo-dind-lib`), so it survives the
+  container being recreated, and `forgejo-dind-prune.timer` drops weekly what
+  has gone a week unused.
+- Bind mounts inside a job's own `docker compose` resolve on the **dind**
+  filesystem, not the job container's. A compose file that bind-mounts the
+  checked-out repo will not see it. Named volumes and `build:` contexts are
+  fine. This is inherent to dind, not to this role.
+
+### Things to know before enabling
+
+- **This runner is shared.** `arbret`, `arbret-biz`, `arbretdos` and
+  `arbret-ops` build here too, and `container.docker_host` is per *runner*, not
+  per repo — every one of them moves onto dind. Their workflows do not change;
+  their next run pulls images into a cold cache.
+- **`capacity` is 4 and dind is one daemon.** Concurrent jobs can see and touch
+  each other's containers and images through the Docker CLI. Forgejo's docs
+  call this out. Fine for a single-tenant runner; set `capacity: 1` if
+  untrusted code ever runs here.
+- **The dind container is `--privileged`**, which is why this belongs on a
+  dedicated CI VM and not beside anything that matters. `forgejo-runner-box`
+  runs the runner and nothing else.
+- **The daemon has no TLS and no authentication.** It is published on
+  `127.0.0.1` only, so reaching it means already having a shell on this box —
+  but it does mean any local user is root in a privileged container. Do not
+  move `forgejo_runner_dind_bind_address` off loopback.
+- **The `runner` user is still in the host `docker` group**, left over from
+  when the runner used the host daemon. With dind it no longer needs it. Worth
+  removing, deliberately, as its own change.
+- **`cache.host` is autodetected**, and job containers now reach the runner's
+  cache server across dind's NAT. Autodetect returns this box's LAN address,
+  which is routable from in there. If `actions/cache` starts silently missing,
+  pin `forgejo_runner_cache_host` — that is the first place to look.
+- **Deploy when the runner is idle.** `shutdown_timeout` is 3h, so restarting
+  it mid-job waits for the job.
+
+### Turning it off
+
+Set `forgejo_runner_dind_enabled: false` and re-run. The role stops and
+disables the units, removes them, and puts `container.docker_host` back to
+`"-"` — the exact configuration this host ran before. The image and the
+`forgejo-dind-lib` volume are left alone: they are a cache, they hold no
+secrets, and deleting them on a toggle is not the role's call.
+
+## `config.yml` is templated now
+
+It used to be `forgejo-runner generate-config`, run once on first deploy and
+never touched again — so the repo had no say in anything inside it, including
+the setting this feature needs. It is now `templates/config.yml.j2`.
+
+Every value in it was transcribed from the file live on `forgejo-runner-box`
+and diffed key-by-key against it: with dind disabled, 30 of 30 keys are
+identical. Two deliberate differences:
+
+- `runner.envs` no longer carries `A_TEST_ENV_NAME_1` / `A_TEST_ENV_NAME_2`,
+  upstream's example placeholders, which were being injected into every job.
+- the upstream comment blob is gone; the values are not.
+
+Because the file is managed, a change to it now restarts the runner
+(`handlers/main.yml`). Previously a config change could not happen at all; the
+failure mode where it lands on disk and the running process never picks it up
+is one this repo has hit before.