SPEC, README and docs rewritten from scratch (closes #154, closes #155, closes #156)

SPEC.md is the only place that says how smallwebwaf behaves and why; docs/ holds lists linking to it; the README is short and links to both. Passed independent review in round 8. Model: fable-5-1 (writing); opus-5-5 (review, merge)
2026-10-26 03:06:28 +01:00
parent eafcc3fd73
commit f408f42b28
21 changed files with 2530 additions and 3978 deletions
@@ -0,0 +1,37 @@
+# What the image holds
+
+The contents of the `smallwebwaf` image, and how each part is pinned.
+"Deployment" in [`SPEC.md`](../SPEC.md) says why each part is there and why it
+is pinned that way.
+
+## Contents
+
+- Ubuntu 26.04 LTS, pinned by digest.
+- `ca-certificates`, `nix-bin` and `runit` from Ubuntu, from the snapshot of its
+  archive at `20261001T000000Z`.
+- Nix, with nixpkgs `nixos-26.05.11045.774debe7a0d1` set up for root as
+  `nixpkgs`. No Nix daemon; `build-users-group =` in `/etc/nix/nix.conf`. Root's
+  Nix profile, `/nix/var/nix/profiles/default/bin`, last on the `PATH`.
+  Unpacked, nixpkgs takes about 500 MiB.
+- `runsvinit` as the entrypoint, built from `github.com/peterbourgon/runsvinit`
+  at a fixed commit hash.
+- The `smallwebwaf` binary, and the user `smallwebwaf` (uid and gid 65532).
+- The service directory `/etc/service/smallwebwaf`, with the `run` script
+  `share/smallwebwaf.run`.
+- `/var/lib/smallwebwaf` for the state files, and `/etc/smallwebwaf/rules.d`
+  with the default rule file `share/rules.d/00-default.rules`.
+- `EXPOSE 8080`, and the `HEALTHCHECK` that runs `smallwebwaf healthcheck`.
+
+## Pins
+
+- Ubuntu's packages: the snapshot service, `--snapshot 20261001T000000Z` on both
+  `apt-get update` and `apt-get install`. The SHA-256 hash of each of the
+  snapshot's `InRelease` files is named in the `Dockerfile` and checked after
+  `apt-get update`. The hashes are the amd64 archive's.
+- nixpkgs: the release file `nixexprs.tar.xz` of
+  `nixos-26.05.11045.774debe7a0d1` on `releases.nixos.org`, named with its
+  SHA-256 hash.
+- `runsvinit`: the archived repository, unchanged since 2015, at its last commit
+  (`b4b2c78`, eight commits after `v2.0.0`), by commit hash, with a `go.mod` the
+  build writes.
+- The Go image that builds `smallwebwaf`: by digest.