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/tasks/configure.yml

@@ -1,23 +1,32 @@
 ---
-- name: Check if config already exists
-  stat:
-    path: "{{ forgejo_runner_config_path }}"
-  register: config_stat
-
-- name: Generate default config
-  shell: "{{ forgejo_runner_bin_path }} generate-config > {{ forgejo_runner_config_path }}"
-  args:
-    chdir: "{{ forgejo_runner_dir }}"
-  when: not config_stat.stat.exists
-
-- name: Set config file ownership
-  file:
-    path: "{{ forgejo_runner_config_path }}"
+# config.yml is a TEMPLATE now, not a one-shot `generate-config`.
+#
+# Before this, the file was generated on first deploy and never touched again,
+# so the repo had no say in anything inside it - including container.docker_host,
+# which is the setting that decides whether jobs can use Docker at all. The
+# alternative was patching keys in place with a regex, which in a YAML file
+# with repeated key names under different parents is the kind of thing that
+# works until it silently does not.
+#
+# owner/group/mode are runner:runner 0644, read off the live box, matching what
+# `generate-config` plus the old chown produced. Nothing secret is in here; the
+# registration token lives in .runner.
+- name: Write the forgejo-runner configuration
+  ansible.builtin.template:
+    src: config.yml.j2
+    dest: "{{ forgejo_runner_config_path }}"
     owner: "{{ forgejo_runner_user }}"
     group: "{{ forgejo_runner_user }}"
-  when: not config_stat.stat.exists
+    mode: '0644'
+    # A malformed config is a runner that will not start. Catch it here, while
+    # the old file is still in place, rather than after it has been replaced.
+    validate: "python3 -c \"import yaml,sys; yaml.safe_load(open(sys.argv[1]))\" %s"
+  notify: Restart forgejo-runner
 
-# ── 6. Register runner ─────────────────────────────────────────────
+# ── Register runner ────────────────────────────────────────────────────────
+# Registration is separate from configuration and happens once. The labels are
+# frozen into .runner at this point; changing forgejo_runner_labels later does
+# not move them, which is why the label set is left exactly as it was.
 - name: Check if runner is already registered
   stat:
     path: "{{ forgejo_runner_dir }}/.runner"
@@ -40,4 +49,3 @@
     owner: "{{ forgejo_runner_user }}"
     group: "{{ forgejo_runner_user }}"
   when: not runner_stat.stat.exists
-

ansible/roles/forgejo_runner/tasks/dind.yml

@@ -0,0 +1,140 @@
+---
+# The isolated Docker daemon jobs build against.
+#
+# Runs BEFORE configure.yml and service.yml on purpose: config.yml names this
+# daemon's address, and forgejo-runner.service Requires= this unit. Creating it
+# after either would mean one run where the runner points at nothing.
+
+# ── Disabled: undo it, do not just skip it ─────────────────────────────────
+# A flag that only ever adds is not a flag. If dind is switched off the runner
+# goes back to container.docker_host "-" a few tasks from now, and a dind still
+# running would be a privileged container nothing uses. The volume and the
+# image are deliberately left: they are the image cache, they hold no secrets,
+# and destroying them on a toggle is not this role's call.
+- name: Find the dind unit when dind is disabled
+  ansible.builtin.stat:
+    path: "/etc/systemd/system/{{ forgejo_runner_dind_service }}.service"
+  register: dind_unit_leftover
+  when: not forgejo_runner_dind_enabled
+
+- name: Stop and disable dind
+  ansible.builtin.systemd:
+    name: "{{ item }}"
+    state: stopped
+    enabled: no
+  loop:
+    - "{{ forgejo_runner_dind_service }}.service"
+    - "{{ forgejo_runner_dind_service }}-prune.timer"
+  failed_when: false
+  when:
+    - not forgejo_runner_dind_enabled
+    - dind_unit_leftover.stat.exists | default(false)
+
+- name: Remove the dind units
+  ansible.builtin.file:
+    path: "/etc/systemd/system/{{ item }}"
+    state: absent
+  loop:
+    - "{{ forgejo_runner_dind_service }}.service"
+    - "{{ forgejo_runner_dind_service }}-prune.service"
+    - "{{ forgejo_runner_dind_service }}-prune.timer"
+  when: not forgejo_runner_dind_enabled
+  notify: Reload systemd
+
+# ── Enabled ───────────────────────────────────────────────────────────────
+- name: Pull the dind image
+  ansible.builtin.command: "docker image pull {{ forgejo_runner_dind_image }}"
+  register: dind_pull
+  changed_when: "'Downloaded newer image' in dind_pull.stdout"
+  when: forgejo_runner_dind_enabled
+
+# Created explicitly rather than left to `docker run`, so that the name is
+# declared here and a later `docker volume ls` has an obvious owner.
+- name: Check for the dind image-store volume
+  ansible.builtin.command: "docker volume inspect {{ forgejo_runner_dind_volume }}"
+  register: dind_volume
+  changed_when: false
+  failed_when: false
+  check_mode: false
+  when: forgejo_runner_dind_enabled
+
+- name: Create the dind image-store volume
+  ansible.builtin.command: "docker volume create {{ forgejo_runner_dind_volume }}"
+  when:
+    - forgejo_runner_dind_enabled
+    - dind_volume.rc | default(1) != 0
+
+- name: Create the dind systemd unit
+  ansible.builtin.template:
+    src: forgejo-dind.service.j2
+    dest: "/etc/systemd/system/{{ forgejo_runner_dind_service }}.service"
+    owner: root
+    group: root
+    mode: '0644'
+  when: forgejo_runner_dind_enabled
+  notify:
+    - Reload systemd
+    - Restart dind
+
+- name: Create the dind prune service
+  ansible.builtin.template:
+    src: forgejo-dind-prune.service.j2
+    dest: "/etc/systemd/system/{{ forgejo_runner_dind_service }}-prune.service"
+    owner: root
+    group: root
+    mode: '0644'
+  when: forgejo_runner_dind_enabled and forgejo_runner_dind_prune_enabled
+  notify: Reload systemd
+
+- name: Create the dind prune timer
+  ansible.builtin.template:
+    src: forgejo-dind-prune.timer.j2
+    dest: "/etc/systemd/system/{{ forgejo_runner_dind_service }}-prune.timer"
+    owner: root
+    group: root
+    mode: '0644'
+  when: forgejo_runner_dind_enabled and forgejo_runner_dind_prune_enabled
+  notify: Reload systemd
+
+- name: Apply pending unit changes before starting dind
+  ansible.builtin.meta: flush_handlers
+
+- name: Enable and start dind
+  ansible.builtin.systemd:
+    name: "{{ forgejo_runner_dind_service }}.service"
+    enabled: yes
+    state: started
+    daemon_reload: yes
+  when: forgejo_runner_dind_enabled
+
+- name: Enable and start the dind prune timer
+  ansible.builtin.systemd:
+    name: "{{ forgejo_runner_dind_service }}-prune.timer"
+    enabled: yes
+    state: started
+    daemon_reload: yes
+  when: forgejo_runner_dind_enabled and forgejo_runner_dind_prune_enabled
+
+# The unit's own ExecStartPost already blocks until the daemon answers, so by
+# here this should be instant. It is asserted anyway, from the same address the
+# runner will use, because "the unit is active" and "the daemon on that port
+# answers" are different claims and it is the second one the runner depends on.
+- name: Verify the dind daemon answers on the address the runner will use
+  ansible.builtin.command: >-
+    docker -H tcp://{{ forgejo_runner_dind_bind_address }}:{{ forgejo_runner_dind_host_port }}
+    version --format {{ '{{.Server.Version}}' }}
+  register: dind_version
+  changed_when: false
+  retries: 10
+  delay: 3
+  until: dind_version.rc == 0
+  when: forgejo_runner_dind_enabled and not ansible_check_mode
+
+- name: Show which daemon the jobs will build on
+  ansible.builtin.debug:
+    msg: >-
+      dind daemon {{ dind_version.stdout }} is up on
+      {{ forgejo_runner_dind_bind_address }}:{{ forgejo_runner_dind_host_port }}
+      (host daemon is untouched); jobs reach it as
+      tcp://{{ forgejo_runner_dind_internal_host }}:{{ forgejo_runner_dind_container_port }}
+  when: forgejo_runner_dind_enabled and not ansible_check_mode

ansible/roles/forgejo_runner/tasks/main.yml

@@ -4,6 +4,9 @@
 # how this refactor was verified against the playbook it replaced.
 - ansible.builtin.import_tasks: prerequisites.yml
 - ansible.builtin.import_tasks: install.yml
+# Before configure.yml and service.yml: config.yml names the dind daemon and
+# forgejo-runner.service Requires= its unit, so it has to exist by then.
+- ansible.builtin.import_tasks: dind.yml
 - ansible.builtin.import_tasks: configure.yml
 - ansible.builtin.import_tasks: service.yml
 - ansible.builtin.import_tasks: healthcheck.yml

ansible/roles/forgejo_runner/tasks/service.yml

@@ -6,6 +6,7 @@
     owner: root
     group: root
     mode: '0644'
+  notify: Restart forgejo-runner
 
 - name: Reload systemd
   systemd:
@@ -17,6 +18,12 @@
     enabled: yes
     state: started
 
+# Before the assert below, not at the end of the play. A config change queues a
+# restart; if that restart ran after the verification, the play would assert
+# that the OLD process is healthy and then replace it unverified.
+- name: Apply a pending restart before checking the runner
+  ansible.builtin.meta: flush_handlers
+
 - name: Verify forgejo-runner is active
   command: systemctl is-active forgejo-runner
   register: runner_active