branderson
67f1028975
The page opened with 592 words before the first click and no indication of how much work was coming. That is most of what made it daunting: not the length, but that the length was unmeasurable from the top. It now opens with the whole job as a five-row table - what you do, where it is, and roughly how much - so the shape and the scale are visible before any of the reasoning. Four of the five rows are one setting or one form; the table says so, and says that step 4 is the substance. Someone who has done this before can go straight to the rule table from there. The console-only argument moved to the end as "Why there is no script for this page". It is the page's philosophy, not something a reader needs before turning on a firewall switch. Verification was one 1,100-word run of prose with the two halves separated by a lowercase "and". It is now two labelled passes, each with its commands first: pass one reads configuration, pass two tests behaviour, and the text says once, at the top, that only the second is proof. `bats test/` 126 passing. docs/building-a-runner.md updated for the renamed anchor.
Documentation
The README is the map: what this is, which tier you want, and how to operate one once it exists. The build itself is two pages, and this is where the second one lives.
| building-a-runner.md | The build, inside the VM: the Debian install, addressing, one bootstrap command, install.sh's settings, and the runners. The same on any hypervisor and for both tiers. Start at your hypervisor's page and it sends you here |
| reference.md | The two settings named docker.sock, CONFIG_FILE and why an edit can appear to do nothing, the /data volume, compose networks against job networks, whether several runners should share a job network, why the privileged runner is separate, why public egress is not restricted on the node, why the resolver is set per-runner, the cache server |
| threat-model.md | The adversary, where each tier's boundary sits, blast radius by layer, and what was rejected |
| upgrading.md | Moving a runner that already exists to a newer version, why the two halves are counted separately, and the seven steps a guest-side change takes when a rollback is going to rebuild the machine |
| ../proxmox/README.md | The node-side half on Proxmox: the VM, the datacenter firewall, the security group and the order its rules go in, and all three snapshot moments including the scheduled rollback |
| ../proxmox/firewall.fw.template | The same node firewall as one annotated file, easier to review in one piece than as a table. Reference, not something to install |
| ../examples/ | The annotated templates dejima-ci-runners renders into ~/runners. Every setting carries the reasoning for its value, which the generated copies do not - read them here rather than reading what lands on the host |
One document lives outside this repository: dejima's docs/ci.md, which
covers why a CI run needs any of this over a sandbox, and why no approval gate
is offered. You do not need it to follow the README.