# What the image holds

The `smallwebwaf` image is the base of each app's own image. The requirements
are under "Deployment" in [`SPEC.md`](../SPEC.md); this file lists what the
image holds, how each part is pinned, and why.

## Contents

- Ubuntu 26.04 LTS, the newest long-term support release of Ubuntu, pinned by
  digest. The image moves to the next LTS release when that ships.
- `ca-certificates`, `nix-bin` and `runit` from Ubuntu, installed from a dated
  snapshot of its archive and checked by hash. The Ubuntu image has no CA
  certificates; without them Nix cannot download packages and `smallwebwaf`
  cannot reach GeoJS.
- Nix and nixpkgs, fixed at one release. Root uses Nix directly; no Nix daemon
  runs. `nix-bin` creates no build users, so `build-users-group =` in
  `/etc/nix/nix.conf` lets root build without them.
- runit, and `runsvinit` as the entrypoint, as the owner's code style guide asks
  for service containers. No package carries `runsvinit`, so the image builds it
  from its archived source (`github.com/peterbourgon/runsvinit`, unchanged
  since 2015) at a fixed commit hash, with a `go.mod` the build writes.
  `runsvinit` starts runit's `runsvdir`, which runs the `run` script of each
  directory under `/etc/service` and runs it again whenever it exits. Ubuntu's
  `sv` looks for services there too.
- The `smallwebwaf` binary, and a user of its own, `smallwebwaf` (uid and gid
  65532).
- The service directory `/etc/service/smallwebwaf`. Its `run` script waits one
  second (`sleep 1`), makes `SWWAF_STATE_DIR` and every file in it belong to the
  `smallwebwaf` user, and starts `smallwebwaf` as that user with runit's
  `chpst`.
- The directory `/var/lib/smallwebwaf` for the state files, and
  `/etc/smallwebwaf/rules.d` with the default rule file.
- Port 8080 declared (`EXPOSE 8080`), and the health check (`HEALTHCHECK`) that
  "The health check" in `SPEC.md` describes.

## Pinning

- Ubuntu's packages come from Ubuntu's snapshot service, the archive as it was
  at the moment the Dockerfile names (`--snapshot 20261001T000000Z`), never
  earlier than the pinned Ubuntu image's date. The Dockerfile names the SHA-256
  hash of each of the snapshot's `InRelease` files, which cover every package
  list and so every package, and the build checks them before installing. The
  hashes are the amd64 archive's, so the image is built for amd64 only. The
  snapshot is fetched over HTTPS with the CA certificates of the Go image that
  builds `smallwebwaf`, itself pinned by digest, since the Ubuntu image has
  none.
- nixpkgs comes from a release file on `releases.nixos.org` (`nixexprs.tar.xz`
  of `nixos-26.05.11045.774debe7a0d1`), named with its SHA-256 hash, not from a
  GitHub archive, whose bytes can change. It is set up for root as `nixpkgs`.
  Root's Nix profile, `/nix/var/nix/profiles/default/bin`, is last on the
  `PATH`, so that no package hides the image's own commands; busybox's `sv`, for
  one, looks for services elsewhere. Unpacked, nixpkgs takes about 500 MiB.
- An app built on the image gets the same packages each time it is built.
  Security fixes from Ubuntu and nixpkgs come with a newer `smallwebwaf` image,
  which an app takes by changing the digest in its `FROM` line. The image moves
  to each new nixpkgs release, every six months.