US08-02: Build a Reproducible Application Image (#97)

README.md

@@ -97,6 +97,55 @@ and the session cookie is marked `Secure` when that external scheme is HTTPS. He
 endpoints stay reachable without the secret so an orchestrator can restart the
 container; nothing else does.
 
+## Container image (US08-02)
+
+One image runs either role. It is built from a clean checkout with no arguments:
+
+```bash
+docker build -t photo-pipeline:dev .
+```
+
+Everything external is pinned, and the build fails rather than drifting: the Python
+base image by tag *and* digest, `exiftool` by its Debian package version (verified
+against `exiftool -ver`), and `immich-go` by release version and per-architecture
+SHA-256 of the release asset. The verified versions become image labels and
+`/etc/photo-pipeline/versions.json`, which `diagnostics` reports as `tools[].pinned`
+beside the version actually installed — so a replaced binary shows up as a
+`tool_version_drift` warning instead of as a misparsed upload report.
+
+| build argument | default | why change it |
+|---|---|---|
+| `UID` / `GID` | `1000` | must match the owner of the mounted photo library |
+| `PYTHON_IMAGE` | pinned digest | upgrading the base image |
+| `EXIFTOOL_VERSION` | Debian package version | upgrading exiftool |
+| `IMMICH_GO_VERSION` + `IMMICH_GO_SHA256_AMD64`/`_ARM64` | pinned release | upgrading the uploader (take the digests from that release's `checksums.txt`) |
+
+The first argument is the role, and every other management command still works:
+
+```bash
+docker run --rm -v /srv/photos:/srv/photos -v pp-data:/data \
+  -e PHOTO_PIPELINE_LIBRARY_ROOTS=/srv/photos photo-pipeline:dev migrate
+
+docker run -d -p 127.0.0.1:8000:8000 -v /srv/photos:/srv/photos -v pp-data:/data \
+  -e PHOTO_PIPELINE_HOST=0.0.0.0 -e PHOTO_PIPELINE_ACCESS_SECRET=... \
+  -e PHOTO_PIPELINE_LIBRARY_ROOTS=/srv/photos photo-pipeline:dev serve
+
+docker run -d -v /srv/photos:/srv/photos -v pp-data:/data \
+  -e PHOTO_PIPELINE_LIBRARY_ROOTS=/srv/photos photo-pipeline:dev worker
+```
+
+One role per container: `serve` and `worker` each take the library process lock for
+their role (US07-05), so no supervisor starts both. The container refuses to run as
+UID 0 — files it renames or writes must keep the ownership the host library expects —
+and `/data` is the persistent volume holding the database, journals, backups, and
+thumbnail cache. Binding to `0.0.0.0` makes the access secret mandatory
+([above](#reaching-it-through-a-hostname-or-proxy-us08-01)); `serve` refuses to start
+without it. The declared `HEALTHCHECK` polls `/api/v1/health/ready`, so a container
+whose database is unmigrated or misconfigured is never reported healthy.
+
+Composing the runtime and mounting the library is US08-03; publishing and deploying
+the image is US08-04.
+
 ## Testing
 
 One offline command runs the whole suite (unit, integration, and browser