feat(MM-66): add Docker image derived from Nix build #4

+1

.gitignore

··· 20 20 .devenv/ 21 21 .direnv/ 22 22 devenv.local.nix 23 23 + /result

+2

CLAUDE.md

··· 11 11 ## Commands 12 12 - `nix develop --impure --accept-flake-config` - Enter dev shell (flags required; --impure for devenv CWD detection, --accept-flake-config activates the Cachix binary cache in nixConfig — without it, a cold build takes 20+ minutes) 13 13 - `nix build .#relay --accept-flake-config` - Build relay binary (output at ./result/bin/relay) 14 14 + - `nix build .#docker-image --accept-flake-config` - Build Docker image tarball (Linux only; output at `./result`; load with `docker load < result`; `docker-image` is not exposed on macOS — use a remote Linux builder or CI) 14 15 - `cargo build` - Build all crates 15 16 - `cargo test` - Run all tests 16 17 - `cargo clippy` - Lint ··· 30 31 - `crates/repo-engine/` - ATProto repo engine 31 32 - `crates/crypto/` - Cryptographic operations 32 33 - `crates/common/` - Shared types and utilities 34 34 + - `nix/` - Nix build helpers (docker.nix produces the relay container image) 33 35 - `docs/` - Specs, design plans, implementation plans 34 36 35 37 ## Conventions

+141

docs/design-plans/2026-03-08-MM-66.md

··· 1 1 + # MM-66: Docker Image Derived from Nix Build 2 2 + 3 3 + ## Summary 4 4 + 5 5 + MM-66 packages the `relay` binary into a Docker image using Nix's `dockerTools.buildLayeredImage`, so the relay can be deployed to any container runtime without manually managing a `Dockerfile` or base OS. The image is produced entirely from the Nix store — no Docker daemon is needed at build time — and includes only the closure of derivations the relay actually needs at runtime: the binary itself, the SQLite shared library, Mozilla CA certificates, and the IANA timezone database. Because every input is a pinned Nix derivation, the image is reproducible: the same `flake.lock` always produces the same bytes. 6 6 + 7 7 + The work is deliberately narrow. A new file, `nix/docker.nix`, holds the image derivation as a self-contained Nix function, and `flake.nix` is extended to expose `docker-image` as a flake output on Linux targets only. Darwin systems are explicitly excluded because `dockerTools.buildLayeredImage` produces Linux container images, and exposing them on macOS would mislead `nix build` callers. The relay binary itself is unchanged; the HTTP layer and `/_health` endpoint verification are deferred to a later ticket. Delivery here is purely the packaging artifact: a tarball that `docker load` accepts and that produces a `relay:latest` image under 50 MB. 8 8 + 9 9 + ## Definition of Done 10 10 + 11 11 + `nix/docker.nix` contains a `buildLayeredImage` derivation that wraps the existing `.#relay` crane build output. `flake.nix` exposes `packages.x86_64-linux.docker-image` and `packages.aarch64-linux.docker-image`. Running `nix build .#docker-image` produces a tarball that can be loaded via `docker load < result`. The image includes the relay binary, SQLite runtime libraries, CA certificates, and timezone data, targeting under 50 MB. The `/_health` acceptance criterion is deferred — this ticket delivers packaging only, not relay HTTP functionality. 12 12 + 13 13 + ## Acceptance Criteria 14 14 + 15 15 + ### MM-66.AC1: docker-image outputs exist in the flake 16 16 + - **MM-66.AC1.1 Success:** `nix flake show --accept-flake-config` (on Linux) lists `packages.x86_64-linux.docker-image` 17 17 + - **MM-66.AC1.2 Success:** `nix flake show --accept-flake-config` (on Linux) lists `packages.aarch64-linux.docker-image` 18 18 + - **MM-66.AC1.3 Negative:** `packages.aarch64-darwin.docker-image` and `packages.x86_64-darwin.docker-image` are not present in `nix flake show` output 19 19 + 20 20 + ### MM-66.AC2: Image builds and loads 21 21 + - **MM-66.AC2.1 Success:** `nix build .#docker-image --accept-flake-config` completes without error on x86_64-linux 22 22 + - **MM-66.AC2.2 Success:** `nix build .#packages.aarch64-linux.docker-image --accept-flake-config` completes without error on an aarch64-linux or x86_64-linux system 23 23 + - **MM-66.AC2.3 Success:** `docker load < result` completes without error 24 24 + - **MM-66.AC2.4 Success:** `docker images` shows `relay:latest` after loading 25 25 + 26 26 + ### MM-66.AC3: Image contents 27 27 + - **MM-66.AC3.1 Success:** `docker run --rm relay:latest` exits without a "no such file" or dynamic linker error (relay binary and libsqlite3.so are present) 28 28 + - **MM-66.AC3.2 Success:** `docker inspect relay:latest` shows `SSL_CERT_FILE` env var pointing to a cacert store path 29 29 + - **MM-66.AC3.3 Success:** `docker inspect relay:latest` shows `TZDIR` env var pointing to a tzdata store path 30 30 + - **MM-66.AC3.4 Success:** `nix/docker.nix` exists and is tracked by git (`git ls-files nix/docker.nix` returns it) 31 31 + 32 32 + ### MM-66.AC4: Image size 33 33 + - **MM-66.AC4.1 Success:** `docker images relay` shows image size under 50 MB 34 34 + 35 35 + ### MM-66.AC5: Scope boundaries 36 36 + - **MM-66.AC5.1 Negative:** `docker run relay:latest` does not require a running HTTP server to start (relay is a stub; no HTTP health check in this ticket) 37 37 + 38 38 + ## Glossary 39 39 + 40 40 + - **derivation**: The fundamental Nix build unit — a description of inputs, a builder script, and a set of outputs that land in the Nix store under a content-addressed path. Everything in a Nix build (compilers, libraries, binaries, Docker images) is a derivation. 41 41 + - **flake**: A Nix project format that pins all inputs in a `flake.lock` file and exposes a structured set of outputs (packages, dev shells, etc.) under a standard schema. `flake.nix` is the entry point. 42 42 + - **flake output**: A named value exported by a flake, addressable as `.#name` on the command line (e.g., `.#docker-image`). Outputs are organized by category (`packages`, `devShells`, etc.) and by system. 43 43 + - **`forEachSystem`**: A helper defined in this flake that maps a function over every supported system string (e.g., `x86_64-linux`, `aarch64-darwin`), producing one set of outputs per platform. 44 44 + - **`pkgs.lib.optionalAttrs`**: A nixpkgs library function that returns an attribute set only when a condition is true, and an empty set otherwise. Used here to gate `docker-image` to Linux systems. 45 45 + - **`pkgs.stdenv.isLinux`**: A boolean in nixpkgs that is `true` when the package set is being evaluated for a Linux target system. 46 46 + - **crane**: A Nix library for building Rust crates. It handles Cargo dependency caching via a separate `buildDepsOnly` derivation so that source-only changes do not trigger a full dependency rebuild. 47 47 + - **`buildLayeredImage`** (`dockerTools.buildLayeredImage`): A nixpkgs function that assembles a Docker image from a list of Nix derivations, splitting them across multiple filesystem layers to maximize layer reuse in container registries. Produces a `.tar.gz` tarball rather than requiring a Docker daemon. 48 48 + - **Nix store**: The immutable, content-addressed directory (typically `/nix/store`) where all derivation outputs live. Paths are of the form `/nix/store/<hash>-<name>`. 49 49 + - **store path**: A specific output directory inside the Nix store, uniquely identified by the hash of its build inputs. Nix embeds these paths directly into build artifacts (e.g., into the `Entrypoint` of a Docker image config). 50 50 + - **`pkgs.sqlite.out`**: The `out` output of the `sqlite` derivation — the split that contains the runtime shared library (`libsqlite3.so`) rather than headers or development files. nixpkgs splits some packages into multiple outputs (`out`, `dev`, `doc`) to reduce closure size. 51 51 + - **`cacert`** (`pkgs.cacert`): A nixpkgs package containing the Mozilla CA certificate bundle. Required for TLS verification in containerized environments that lack a system certificate store. 52 52 + - **`tzdata`** (`pkgs.tzdata`): A nixpkgs package containing the IANA timezone database. Required at runtime for any Rust code that resolves timezone names. 53 53 + - **`SSL_CERT_FILE`**: An environment variable recognised by OpenSSL and most TLS stacks that points to the CA certificate bundle file. Set in the Docker image config to the cacert store path. 54 54 + - **`TZDIR`**: An environment variable recognised by the C library and Rust's `time`/`chrono` crates that points to the timezone database directory. Set in the Docker image config to the tzdata store path. 55 55 + - **`cargoArtifacts`**: Crane's name for the pre-built dependency artifact set produced by `buildDepsOnly`. Passed into `buildPackage` so incremental rebuilds skip recompiling dependencies. 56 56 + - **closure**: In Nix, the full set of store paths that a derivation depends on transitively. The Docker image's closure is exactly what ends up in its filesystem layers. 57 57 + - **`self.shortRev`**: A flake variable holding the short git commit hash of the repository at build time. Mentioned in the tag strategy as a future replacement for `"latest"` to produce traceable image tags. Note: `self.shortRev` is absent on dirty trees (uncommitted changes), causing a flake evaluation error unless guarded as `self.shortRev or "dev"`. 58 58 + - **stub**: Used in this document to mean the relay binary currently compiles and exits but does not serve HTTP traffic. The Docker packaging is tested against this stub rather than a fully functional server. 59 59 + 60 60 + ## Architecture 61 61 + 62 62 + Minimal two-file change. `nix/docker.nix` is a new Nix package expression; `flake.nix` is extended to expose it as a flake output on Linux systems. 63 63 + 64 64 + ``` 65 65 + repo root/ 66 66 + ├── flake.nix # extend forEachSystem — add docker-image on Linux 67 67 + └── nix/ 68 68 + └── docker.nix # new — buildLayeredImage derivation 69 69 + ``` 70 70 + 71 71 + `nix/docker.nix` is a function `{ pkgs, relay }:` that returns a `dockerTools.buildLayeredImage` derivation. The function receives `pkgs` (the nixpkgs instance for the target system) and `relay` (the crane-built binary derivation from `flake.nix`). This is the standard nixpkgs package expression pattern: a function that takes its dependencies as arguments. 72 72 + 73 73 + `flake.nix` extends the existing `forEachSystem` lambda using `pkgs.lib.optionalAttrs pkgs.stdenv.isLinux { ... }`. On Linux systems (`x86_64-linux`, `aarch64-linux`), the lambda returns `relay`, `default`, and `docker-image`. On Darwin systems, it returns only `relay` and `default`. No additional `genAttrs` or helper function is needed. 74 74 + 75 75 + The resulting new flake outputs: 76 76 + - `packages.x86_64-linux.docker-image` 77 77 + - `packages.aarch64-linux.docker-image` 78 78 + 79 79 + **Image contents:** 80 80 + 81 81 + | Derivation | Purpose | 82 82 + |---|---| 83 83 + | `relay` | The crane-built binary; store path used as `Entrypoint` | 84 84 + | `pkgs.sqlite.out` | Runtime `libsqlite3.so`; `.out` output carries shared libraries, not headers | 85 85 + | `pkgs.cacert` | Mozilla CA bundle; referenced via `SSL_CERT_FILE` env var | 86 86 + | `pkgs.tzdata` | IANA timezone database; referenced via `TZDIR` env var | 87 87 + 88 88 + `config.Entrypoint = [ "${relay}/bin/relay" ]` — Nix evaluates the store path at build time, so the entrypoint is always tied to the exact derivation. `ExposedPorts` is omitted until the relay has a known HTTP port. `tag = "latest"` is a placeholder; it can be wired to `self.shortRev` for reproducible tagging once the relay is deployed. 89 89 + 90 90 + **Build workflow on Linux:** 91 91 + ```bash 92 92 + nix build .#docker-image --accept-flake-config # produces ./result 93 93 + docker load < result # loads relay:latest 94 94 + docker run --rm relay:latest 95 95 + ``` 96 96 + 97 97 + On macOS, `nix build .#docker-image` fails — `docker-image` is not exposed for Darwin systems. Use `nix build .#packages.aarch64-linux.docker-image` with a remote Linux builder, or rely on CI. 98 98 + 99 99 + ## Existing Patterns 100 100 + 101 101 + The function-per-file pattern (`{ pkgs, relay }:` returning a derivation) mirrors how nixpkgs package expressions are structured. It is the same approach used by the existing `flake.nix` to wire `crane` and `rust-overlay`. 102 102 + 103 103 + The `pkgs.lib.optionalAttrs pkgs.stdenv.isLinux { ... }` conditional follows the same `forEachSystem` structure established in MM-64 for multi-platform flake outputs, and the same `commonArgs` / `buildPackage` pattern established in MM-65 for the relay crane build. The `nix/` subdirectory is introduced here as the canonical location for distribution-channel derivations (Docker image, and in the future, NixOS module). 104 104 + 105 105 + ## Implementation Phases 106 106 + 107 107 + <!-- START_PHASE_1 --> 108 108 + ### Phase 1: Write derivation files 109 109 + **Goal:** Create `nix/docker.nix` and extend `flake.nix` so the docker-image output is exposed on Linux. 110 110 + 111 111 + **Components:** 112 112 + - `nix/docker.nix` — function `{ pkgs, relay }:` returning `pkgs.dockerTools.buildLayeredImage` with `contents = [ relay pkgs.sqlite.out pkgs.cacert pkgs.tzdata ]`, `Entrypoint`, and `Env` for `SSL_CERT_FILE` and `TZDIR` 113 113 + - `flake.nix` — extend the `forEachSystem` return value with `// pkgs.lib.optionalAttrs pkgs.stdenv.isLinux { docker-image = import ./nix/docker.nix { inherit pkgs relay; }; }` 114 114 + 115 115 + **Dependencies:** None (MM-65 relay build is already in `flake.nix`) 116 116 + 117 117 + **Done when:** `nix flake show --accept-flake-config` (on Linux) lists `packages.x86_64-linux.docker-image` and `packages.aarch64-linux.docker-image`; file `nix/docker.nix` exists and is tracked by git 118 118 + <!-- END_PHASE_1 --> 119 119 + 120 120 + <!-- START_PHASE_2 --> 121 121 + ### Phase 2: Build verification 122 122 + **Goal:** Confirm the image builds, loads, and runs on Linux; verify size target. 123 123 + 124 124 + **Components:** 125 125 + - CI or Linux shell verification: `nix build .#docker-image --accept-flake-config` succeeds 126 126 + - `docker load < result` loads without error; `docker images` shows `relay:latest` 127 127 + - `docker run --rm relay:latest` exits (relay is currently a stub) 128 128 + - Image size reported by `docker images` is under 50 MB 129 129 + 130 130 + **Dependencies:** Phase 1 131 131 + 132 132 + **Done when:** All four verification steps above pass on an x86_64-linux or aarch64-linux system; CLAUDE.md updated to note that `docker-image` is Linux-only and macOS requires a remote builder or CI 133 133 + <!-- END_PHASE_2 --> 134 134 + 135 135 + ## Additional Considerations 136 136 + 137 137 + **macOS builds:** `nix build .#docker-image` will fail on Darwin — `docker-image` is intentionally not exposed for Darwin systems. Developers on macOS who need to build Docker images locally must configure a remote Linux builder (nix-darwin's `linux-builder` feature provides an aarch64-linux VM via Apple's Virtualization framework) or delegate to CI. 138 138 + 139 139 + **Tag strategy:** `tag = "latest"` is a placeholder. Once the relay has a release process, wire this to `self.shortRev or "dev"` in `flake.nix` to produce reproducible, traceable tags. 140 140 + 141 141 + **`/_health` deferral:** The acceptance criterion requiring `docker run` to respond to `/_health` is intentionally out of scope. It will be verified once the relay gains an HTTP server in a later ticket. The Docker packaging design is independent of relay HTTP functionality.

+176

docs/implementation-plans/2026-03-08-MM-66/phase_01.md

··· 1 1 + # MM-66 Docker Image Implementation Plan — Phase 1 2 2 + 3 3 + **Goal:** Create `nix/docker.nix` and extend `flake.nix` so `docker-image` is exposed as a flake package on Linux targets only. 4 4 + 5 5 + **Architecture:** A new file `nix/docker.nix` holds the `buildLayeredImage` derivation as a standalone Nix function `{ pkgs, relay }:`. `flake.nix` merges this into the existing `forEachSystem` lambda return value using `pkgs.lib.optionalAttrs pkgs.stdenv.isLinux { ... }`, which evaluates to `{}` on Darwin and `{ docker-image = ...; }` on Linux — making the conditional a zero-cost no-op on macOS. 6 6 + 7 7 + **Tech Stack:** Nix flakes, nixpkgs `dockerTools.buildLayeredImage`, crane (relay binary already built by MM-65) 8 8 + 9 9 + **Scope:** Phase 1 of 2 from the original design. Phase 2 covers build verification and CLAUDE.md update. 10 10 + 11 11 + **Codebase verified:** 2026-03-08 12 12 + 13 13 + --- 14 14 + 15 15 + ## Acceptance Criteria Coverage 16 16 + 17 17 + This phase implements: 18 18 + 19 19 + ### MM-66.AC1: docker-image outputs exist in the flake 20 20 + - **MM-66.AC1.1 Success:** `nix flake show --accept-flake-config` (on Linux) lists `packages.x86_64-linux.docker-image` 21 21 + - **MM-66.AC1.2 Success:** `nix flake show --accept-flake-config` (on Linux) lists `packages.aarch64-linux.docker-image` 22 22 + - **MM-66.AC1.3 Negative:** `packages.aarch64-darwin.docker-image` and `packages.x86_64-darwin.docker-image` are not present in `nix flake show` output 23 23 + 24 24 + ### MM-66.AC3: Image contents 25 25 + - **MM-66.AC3.4 Success:** `nix/docker.nix` exists and is tracked by git (`git ls-files nix/docker.nix` returns it) 26 26 + 27 27 + > **Note on AC1.1 / AC1.2:** These require a Linux system to verify. On macOS, `nix flake show` will not list `docker-image` (AC1.3 is verifiable now; AC1.1 and AC1.2 are verified in Phase 2 on a Linux system or CI). 28 28 + 29 29 + --- 30 30 + 31 31 + <!-- START_SUBCOMPONENT_A (tasks 1-3) --> 32 32 + 33 33 + <!-- START_TASK_1 --> 34 34 + ### Task 1: Create `nix/docker.nix` 35 35 + 36 36 + **Files:** 37 37 + - Create: `nix/docker.nix` 38 38 + 39 39 + **Step 1: Create the `nix/` directory and write the derivation** 40 40 + 41 41 + ```bash 42 42 + mkdir nix 43 43 + ``` 44 44 + 45 45 + Then create `nix/docker.nix` with exactly this content: 46 46 + 47 47 + ```nix 48 48 + { pkgs, relay }: 49 49 + pkgs.dockerTools.buildLayeredImage { 50 50 + name = "relay"; 51 51 + tag = "latest"; 52 52 + contents = [ relay pkgs.sqlite.out pkgs.cacert pkgs.tzdata ]; 53 53 + config = { 54 54 + Entrypoint = [ "${relay}/bin/relay" ]; 55 55 + Env = [ 56 56 + "SSL_CERT_FILE=${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt" 57 57 + "TZDIR=${pkgs.tzdata}/share/zoneinfo" 58 58 + ]; 59 59 + }; 60 60 + } 61 61 + ``` 62 62 + 63 63 + **Explanation of each field:** 64 64 + - `name = "relay"`: The Docker image name that appears in `docker images`. 65 65 + - `tag = "latest"`: Placeholder tag; can be wired to `self.shortRev` later. 66 66 + - `contents`: List of derivations whose closure becomes the image filesystem. `pkgs.sqlite.out` is the runtime-library output of sqlite (carries `libsqlite3.so`); `.dev` (headers) is omitted. 67 67 + - `Entrypoint`: Uses Nix string interpolation — `${relay}` expands to the relay's `/nix/store/...` path at evaluation time, so the entrypoint is always tied to the exact derivation. 68 68 + - `SSL_CERT_FILE` / `TZDIR`: Point into the Nix store paths of `cacert` and `tzdata` so TLS and timezone lookups work inside the container. 69 69 + 70 70 + **Step 2: No operational verification yet** — verification happens after flake.nix is updated in Task 2. 71 71 + 72 72 + <!-- END_TASK_1 --> 73 73 + 74 74 + <!-- START_TASK_2 --> 75 75 + ### Task 2: Extend `flake.nix` to expose `docker-image` on Linux 76 76 + 77 77 + **Files:** 78 78 + - Modify: `flake.nix:48-51` 79 79 + 80 80 + **Current content at lines 48–51:** 81 81 + 82 82 + ```nix 83 83 + in { 84 84 + inherit relay; 85 85 + default = relay; 86 86 + } 87 87 + ``` 88 88 + 89 89 + **Replace with:** 90 90 + 91 91 + ```nix 92 92 + in { 93 93 + inherit relay; 94 94 + default = relay; 95 95 + } // pkgs.lib.optionalAttrs pkgs.stdenv.isLinux { 96 96 + docker-image = import ./nix/docker.nix { inherit pkgs relay; }; 97 97 + } 98 98 + ``` 99 99 + 100 100 + **Why `pkgs.lib.optionalAttrs`:** Returns the attribute set when the condition is true, and `{}` otherwise. On Darwin, the merge is `{ inherit relay; default = relay; } // {} = { inherit relay; default = relay; }`. On Linux, the `docker-image` attribute is added. This keeps Darwin package outputs unchanged while adding the Linux-only output. 101 101 + 102 102 + **Why `import ./nix/docker.nix { inherit pkgs relay; }`:** Calls the function in `nix/docker.nix` with the current `pkgs` (for the target system) and the crane-built `relay` derivation. This is the standard nixpkgs package-expression calling convention. 103 103 + 104 104 + **Step 2: Verify the flake evaluates (catches Nix syntax errors)** 105 105 + 106 106 + ```bash 107 107 + nix flake show --accept-flake-config 108 108 + ``` 109 109 + 110 110 + Expected on macOS (aarch64-darwin): Output shows `packages.aarch64-darwin` with `relay` and `default`, but **no** `docker-image`. This is correct — `pkgs.stdenv.isLinux` is `false` on Darwin. 111 111 + 112 112 + Example output (macOS): 113 113 + ``` 114 114 + git+file:///path/to/ezpds 115 115 + ├───devShells 116 116 + │ ├───aarch64-darwin 117 117 + │ │ └───default: development environment 'devenv-shell' 118 118 + │ ... 119 119 + └───packages 120 120 + ├───aarch64-darwin 121 121 + │ ├───default: package 'relay-0.1.0' 122 122 + │ └───relay: package 'relay-0.1.0' 123 123 + ├───aarch64-linux 124 124 + │ ├───default: package 'relay-0.1.0' 125 125 + │ ├───docker-image: package 'docker-image.tar.gz' 126 126 + │ └───relay: package 'relay-0.1.0' 127 127 + ... 128 128 + ``` 129 129 + 130 130 + If the command errors with a Nix eval error, fix it before proceeding to Task 3. 131 131 + 132 132 + <!-- END_TASK_2 --> 133 133 + 134 134 + <!-- START_TASK_3 --> 135 135 + ### Task 3: Track files in git and commit 136 136 + 137 137 + **Files:** 138 138 + - `nix/docker.nix` (new) 139 139 + - `flake.nix` (modified) 140 140 + 141 141 + **Step 1: Stage both files** 142 142 + 143 143 + ```bash 144 144 + git add nix/docker.nix flake.nix 145 145 + ``` 146 146 + 147 147 + **Step 2: Verify AC3.4 — `nix/docker.nix` is tracked by git** 148 148 + 149 149 + ```bash 150 150 + git ls-files nix/docker.nix 151 151 + ``` 152 152 + 153 153 + Expected output: 154 154 + ``` 155 155 + nix/docker.nix 156 156 + ``` 157 157 + 158 158 + If empty, the file is not staged/tracked. Re-run `git add nix/docker.nix`. 159 159 + 160 160 + **Step 3: Verify AC1.3 (negative) on macOS — `docker-image` is NOT present for Darwin** 161 161 + 162 162 + ```bash 163 163 + nix flake show --accept-flake-config 2>/dev/null | grep docker-image 164 164 + ``` 165 165 + 166 166 + Expected: Lines for `aarch64-linux` and `x86_64-linux` only. No `aarch64-darwin` or `x86_64-darwin` lines. If `docker-image` appears under a Darwin system, the `optionalAttrs` condition is wrong — re-check Task 2. 167 167 + 168 168 + **Step 4: Commit** 169 169 + 170 170 + ```bash 171 171 + git commit -m "feat(MM-66): add nix/docker.nix and expose docker-image on Linux" 172 172 + ``` 173 173 + 174 174 + <!-- END_TASK_3 --> 175 175 + 176 176 + <!-- END_SUBCOMPONENT_A -->

+230

docs/implementation-plans/2026-03-08-MM-66/phase_02.md

··· 1 1 + # MM-66 Docker Image Implementation Plan — Phase 2 2 2 + 3 3 + **Goal:** Update CLAUDE.md with the `docker-image` Linux-only caveat, then verify the image builds, loads, runs, and meets size constraints on a Linux system. 4 4 + 5 5 + **Architecture:** No new Nix code. This phase has one code change (CLAUDE.md), and the remaining work is operational verification that must be executed on an x86_64-linux or aarch64-linux system (or via CI). All acceptance criteria in this phase require a Linux Docker daemon. 6 6 + 7 7 + **Tech Stack:** Nix CLI, Docker CLI (Linux only) 8 8 + 9 9 + **Scope:** Phase 2 of 2. Phase 1 created `nix/docker.nix` and extended `flake.nix`. 10 10 + 11 11 + **Codebase verified:** 2026-03-08 12 12 + 13 13 + --- 14 14 + 15 15 + ## Acceptance Criteria Coverage 16 16 + 17 17 + This phase verifies: 18 18 + 19 19 + ### MM-66.AC2: Image builds and loads 20 20 + - **MM-66.AC2.1 Success:** `nix build .#docker-image --accept-flake-config` completes without error on x86_64-linux 21 21 + - **MM-66.AC2.2 Success:** `nix build .#packages.aarch64-linux.docker-image --accept-flake-config` completes without error on an aarch64-linux or x86_64-linux system 22 22 + - **MM-66.AC2.3 Success:** `docker load < result` completes without error 23 23 + - **MM-66.AC2.4 Success:** `docker images` shows `relay:latest` after loading 24 24 + 25 25 + ### MM-66.AC3: Image contents 26 26 + - **MM-66.AC3.1 Success:** `docker run --rm relay:latest` exits without a "no such file" or dynamic linker error (relay binary and libsqlite3.so are present) 27 27 + - **MM-66.AC3.2 Success:** `docker inspect relay:latest` shows `SSL_CERT_FILE` env var pointing to a cacert store path 28 28 + - **MM-66.AC3.3 Success:** `docker inspect relay:latest` shows `TZDIR` env var pointing to a tzdata store path 29 29 + 30 30 + ### MM-66.AC4: Image size 31 31 + - **MM-66.AC4.1 Success:** `docker images relay` shows image size under 50 MB 32 32 + 33 33 + ### MM-66.AC5: Scope boundaries 34 34 + - **MM-66.AC5.1 Negative:** `docker run relay:latest` does not require a running HTTP server to start (relay is a stub; no HTTP health check in this ticket) 35 35 + 36 36 + --- 37 37 + 38 38 + > **All verification in this phase requires a Linux system with Docker installed.** 39 39 + > On macOS, `docker-image` is not exposed (by design). Use a Linux CI runner or a remote Linux builder. 40 40 + 41 41 + --- 42 42 + 43 43 + <!-- START_SUBCOMPONENT_A (tasks 1-2) --> 44 44 + 45 45 + <!-- START_TASK_1 --> 46 46 + ### Task 1: Update CLAUDE.md with `docker-image` Linux-only note 47 47 + 48 48 + **Files:** 49 49 + - Modify: `CLAUDE.md:13` (after the `nix build .#relay` line) 50 50 + 51 51 + **Current content at line 13:** 52 52 + 53 53 + ``` 54 54 + - `nix build .#relay --accept-flake-config` - Build relay binary (output at ./result/bin/relay) 55 55 + ``` 56 56 + 57 57 + **Add the following line immediately after line 13:** 58 58 + 59 59 + ``` 60 60 + - `nix build .#docker-image --accept-flake-config` - Build Docker image tarball (Linux only; `docker-image` is not exposed on macOS — use a remote Linux builder or CI) 61 61 + ``` 62 62 + 63 63 + The full Commands section should read: 64 64 + 65 65 + ```markdown 66 66 + ## Commands 67 67 + - `nix develop --impure --accept-flake-config` - Enter dev shell (flags required; --impure for devenv CWD detection, --accept-flake-config activates the Cachix binary cache in nixConfig — without it, a cold build takes 20+ minutes) 68 68 + - `nix build .#relay --accept-flake-config` - Build relay binary (output at ./result/bin/relay) 69 69 + - `nix build .#docker-image --accept-flake-config` - Build Docker image tarball (Linux only; `docker-image` is not exposed on macOS — use a remote Linux builder or CI) 70 70 + - `cargo build` - Build all crates 71 71 + - `cargo test` - Run all tests 72 72 + - `cargo clippy` - Lint 73 73 + - `cargo fmt --check` - Check formatting 74 74 + ``` 75 75 + 76 76 + **Verification:** 77 77 + 78 78 + ```bash 79 79 + grep "docker-image" CLAUDE.md 80 80 + ``` 81 81 + 82 82 + Expected: One line mentioning `nix build .#docker-image` and noting it is Linux-only. 83 83 + 84 84 + **Commit:** 85 85 + 86 86 + ```bash 87 87 + git add CLAUDE.md 88 88 + git commit -m "docs(MM-66): note docker-image is Linux-only in CLAUDE.md" 89 89 + ``` 90 90 + 91 91 + <!-- END_TASK_1 --> 92 92 + 93 93 + <!-- START_TASK_2 --> 94 94 + ### Task 2: Verify image on Linux (human verification checklist) 95 95 + 96 96 + > **Run these steps on an x86_64-linux or aarch64-linux system with Docker installed.** 97 97 + > This task documents acceptance-criteria verification — it is not automated. 98 98 + 99 99 + --- 100 100 + 101 101 + **Step 1: Build x86_64-linux image (verifies MM-66.AC2.1)** 102 102 + 103 103 + ```bash 104 104 + nix build .#docker-image --accept-flake-config 105 105 + ``` 106 106 + 107 107 + Expected: Exits 0. A `result` symlink appears pointing to a `.tar.gz` in the Nix store. 108 108 + 109 109 + If it fails with an eval error, ensure Phase 1 commit is present and re-check `nix/docker.nix` and `flake.nix`. 110 110 + 111 111 + --- 112 112 + 113 113 + **Step 2: Build aarch64-linux image (verifies MM-66.AC2.2)** 114 114 + 115 115 + On an x86_64-linux host (cross-compilation): 116 116 + 117 117 + ```bash 118 118 + nix build .#packages.aarch64-linux.docker-image --accept-flake-config 119 119 + ``` 120 120 + 121 121 + Expected: Exits 0. A `result` symlink appears for the aarch64 image. 122 122 + 123 123 + > Cross-compilation for aarch64 requires binfmt\_misc QEMU support or a configured remote builder. If unavailable, skip this step and mark it verified via CI. 124 124 + 125 125 + --- 126 126 + 127 127 + **Step 3: Load image into Docker (verifies MM-66.AC2.3 and MM-66.AC2.4)** 128 128 + 129 129 + First rebuild the x86_64 image if `result` is from the aarch64 build: 130 130 + 131 131 + ```bash 132 132 + nix build .#docker-image --accept-flake-config 133 133 + ``` 134 134 + 135 135 + Then load: 136 136 + 137 137 + ```bash 138 138 + docker load < result 139 139 + ``` 140 140 + 141 141 + Expected output contains: 142 142 + ``` 143 143 + Loaded image: relay:latest 144 144 + ``` 145 145 + 146 146 + Verify the image appears: 147 147 + 148 148 + ```bash 149 149 + docker images relay 150 150 + ``` 151 151 + 152 152 + Expected: At least one row showing `relay` / `latest`. 153 153 + 154 154 + --- 155 155 + 156 156 + **Step 4: Run the relay stub (verifies MM-66.AC3.1 and MM-66.AC5.1)** 157 157 + 158 158 + ```bash 159 159 + docker run --rm relay:latest 160 160 + ``` 161 161 + 162 162 + Expected: The container exits. There must be **no** `no such file or directory` or `error while loading shared libraries: libsqlite3.so` error. 163 163 + 164 164 + The relay is currently a stub and may exit with a non-zero code — that is acceptable. The absence of linker errors confirms `relay` binary and `libsqlite3.so` are present in the image closure. 165 165 + 166 166 + --- 167 167 + 168 168 + **Step 5: Inspect environment variables (verifies MM-66.AC3.2 and MM-66.AC3.3)** 169 169 + 170 170 + ```bash 171 171 + docker inspect relay:latest | grep -E 'SSL_CERT_FILE|TZDIR' 172 172 + ``` 173 173 + 174 174 + Expected output (store hash will differ): 175 175 + 176 176 + ``` 177 177 + "SSL_CERT_FILE=/nix/store/...-nss-ca-cert-.../etc/ssl/certs/ca-bundle.crt", 178 178 + "TZDIR=/nix/store/...-tzdata-.../share/zoneinfo" 179 179 + ``` 180 180 + 181 181 + Both variables must be present. If either is missing, `nix/docker.nix` is missing the `Env` config — re-check Task 1 of Phase 1. 182 182 + 183 183 + --- 184 184 + 185 185 + **Step 6: Check image size (verifies MM-66.AC4.1)** 186 186 + 187 187 + ```bash 188 188 + docker images relay --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}" 189 189 + ``` 190 190 + 191 191 + Expected: The `SIZE` column shows a value under 50 MB (e.g., `42.3MB`). 192 192 + 193 193 + If the size exceeds 50 MB, check `contents` in `nix/docker.nix` for unnecessary packages and remove them. The expected closure is: relay binary + libsqlite3.so + CA bundle + tzdata. No shell, no libc extras. 194 194 + 195 195 + --- 196 196 + 197 197 + **Step 7: Verify `docker-image` is absent on Darwin (verifies MM-66.AC1.3)** 198 198 + 199 199 + From your macOS machine: 200 200 + 201 201 + ```bash 202 202 + nix flake show --accept-flake-config 2>/dev/null | grep docker-image 203 203 + ``` 204 204 + 205 205 + Expected: Lines for `aarch64-linux` and `x86_64-linux` only. No `aarch64-darwin` or `x86_64-darwin` lines appear. 206 206 + 207 207 + --- 208 208 + 209 209 + **Step 8: Verify flake show on Linux lists both outputs (verifies MM-66.AC1.1 and MM-66.AC1.2)** 210 210 + 211 211 + On the Linux system: 212 212 + 213 213 + ```bash 214 214 + nix flake show --accept-flake-config 2>/dev/null | grep docker-image 215 215 + ``` 216 216 + 217 217 + Expected output includes: 218 218 + ``` 219 219 + │ ├───aarch64-linux 220 220 + │ │ ├───docker-image: package 'docker-image.tar.gz' 221 221 + │ ... 222 222 + │ ├───x86_64-linux 223 223 + │ │ ├───docker-image: package 'docker-image.tar.gz' 224 224 + ``` 225 225 + 226 226 + Both `aarch64-linux` and `x86_64-linux` must show `docker-image`. 227 227 + 228 228 + <!-- END_TASK_2 --> 229 229 + 230 230 + <!-- END_SUBCOMPONENT_A -->

+83

docs/implementation-plans/2026-03-08-MM-66/test-requirements.md

··· 1 1 + # MM-66 Test Requirements 2 2 + 3 3 + ## Overview 4 4 + 5 5 + MM-66 is a Nix/Docker packaging ticket. There is no Rust application logic under test -- the implementation consists entirely of Nix derivation files (`nix/docker.nix` and a `flake.nix` extension). Consequently, there are no Rust unit tests or integration tests in scope. All verification is operational: checking that Nix flake outputs exist, that the built Docker image loads and runs correctly, and that the image meets size and content constraints. 6 6 + 7 7 + Verification splits into two categories: 8 8 + 9 9 + 1. **Automated (CI-able on Linux):** Checks that can be scripted and run in a Linux CI environment with Nix and Docker installed. These are shell commands with deterministic expected output. 10 10 + 2. **Human verification (Linux required):** Checks that require a running Docker daemon on a Linux system. These cannot be run on macOS (where the current development happens) because `docker-image` is intentionally not exposed for Darwin targets. A developer must either use a Linux machine, a remote Linux builder, or a Linux CI runner. 11 11 + 12 12 + In practice, every AC in this ticket requires Linux for full verification. The distinction below separates checks that are purely Nix evaluation (can run without Docker) from checks that require both Nix and a Docker daemon. 13 13 + 14 14 + ## Automated Tests 15 15 + 16 16 + These checks can be scripted in CI. They verify Nix flake structure and file tracking -- no Docker daemon required. 17 17 + 18 18 + | AC ID | Test Type | Verification Command | What It Verifies | 19 19 + |---|---|---|---| 20 20 + | AC1.3 | Nix flake evaluation (macOS or Linux) | `nix flake show --accept-flake-config 2>/dev/null \| grep docker-image` | `docker-image` appears only under `aarch64-linux` and `x86_64-linux` -- never under `aarch64-darwin` or `x86_64-darwin`. Verifiable on any platform because `nix flake show` evaluates all systems. | 21 21 + | AC3.4 | Git file tracking | `git ls-files nix/docker.nix` | `nix/docker.nix` exists and is tracked by git (output is `nix/docker.nix`). | 22 22 + 23 23 + **Notes:** 24 24 + - AC1.3 is the only acceptance criterion fully verifiable on macOS. The `nix flake show` output lists all systems regardless of the host platform, so a grep for `docker-image` under Darwin systems can confirm absence. 25 25 + - AC3.4 is a simple git check with no platform dependency. 26 26 + 27 27 + ## Human Verification (Linux Required) 28 28 + 29 29 + All remaining ACs require a Linux system with both Nix and Docker installed. The commands below are taken directly from Phase 2, Task 2 of the implementation plan. 30 30 + 31 31 + ### AC1: docker-image outputs exist in the flake 32 32 + 33 33 + | AC ID | Verification Command | Expected Result | Justification for Human Verification | 34 34 + |---|---|---|---| 35 35 + | AC1.1 | `nix flake show --accept-flake-config 2>/dev/null \| grep docker-image` | Output includes `packages.x86_64-linux.docker-image` (or the tree-formatted equivalent showing `docker-image: package 'docker-image.tar.gz'` under `x86_64-linux`) | While `nix flake show` works on any platform, confirming the output is correct on an actual Linux system validates that the conditional evaluation produces the expected attribute. Can be automated in Linux CI. | 36 36 + | AC1.2 | `nix flake show --accept-flake-config 2>/dev/null \| grep docker-image` | Output includes `packages.aarch64-linux.docker-image` (or the tree-formatted equivalent showing `docker-image: package 'docker-image.tar.gz'` under `aarch64-linux`) | Same as AC1.1. Both architectures must appear. | 37 37 + 38 38 + ### AC2: Image builds and loads 39 39 + 40 40 + | AC ID | Verification Command | Expected Result | Justification for Human Verification | 41 41 + |---|---|---|---| 42 42 + | AC2.1 | `nix build .#docker-image --accept-flake-config` | Exits 0. A `result` symlink appears pointing to a `.tar.gz` in the Nix store. | Requires Linux -- `docker-image` is not a valid flake output on Darwin. The Nix build actually compiles the image derivation. | 43 43 + | AC2.2 | `nix build .#packages.aarch64-linux.docker-image --accept-flake-config` | Exits 0. A `result` symlink appears for the aarch64 image. | Requires Linux (or cross-compilation with binfmt_misc QEMU support). May need to be verified via CI if no aarch64 system is available. | 44 44 + | AC2.3 | `docker load < result` | Output contains `Loaded image: relay:latest`. | Requires Docker daemon on Linux. | 45 45 + | AC2.4 | `docker images relay` | At least one row showing `relay` / `latest`. | Requires Docker daemon on Linux. | 46 46 + 47 47 + ### AC3: Image contents 48 48 + 49 49 + | AC ID | Verification Command | Expected Result | Justification for Human Verification | 50 50 + |---|---|---|---| 51 51 + | AC3.1 | `docker run --rm relay:latest` | Container exits without `no such file or directory` or `error while loading shared libraries: libsqlite3.so` errors. Non-zero exit code is acceptable (relay is a stub). | Requires Docker daemon on Linux. Validates that the relay binary and libsqlite3.so are present in the image closure. | 52 52 + | AC3.2 | `docker inspect relay:latest \| grep -E 'SSL_CERT_FILE'` | Output shows `SSL_CERT_FILE=/nix/store/...-nss-ca-cert-.../etc/ssl/certs/ca-bundle.crt` (exact store hash varies). | Requires Docker daemon on Linux. Validates the cacert environment variable is set in the image config. | 53 53 + | AC3.3 | `docker inspect relay:latest \| grep -E 'TZDIR'` | Output shows `TZDIR=/nix/store/...-tzdata-.../share/zoneinfo` (exact store hash varies). | Requires Docker daemon on Linux. Validates the tzdata environment variable is set in the image config. | 54 54 + 55 55 + ### AC4: Image size 56 56 + 57 57 + | AC ID | Verification Command | Expected Result | Justification for Human Verification | 58 58 + |---|---|---|---| 59 59 + | AC4.1 | `docker images relay --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"` | SIZE column shows a value under 50 MB. | Requires Docker daemon on Linux. Image must be loaded first (AC2.3). | 60 60 + 61 61 + ### AC5: Scope boundaries 62 62 + 63 63 + | AC ID | Verification Command | Expected Result | Justification for Human Verification | 64 64 + |---|---|---|---| 65 65 + | AC5.1 | `docker run --rm relay:latest` | Container exits (same command as AC3.1). The relay does not attempt to start an HTTP server or listen on a port. No health check endpoint is tested. | Requires Docker daemon on Linux. Confirms the relay is a stub -- packaging only, no HTTP functionality in this ticket. | 66 66 + 67 67 + ## AC Coverage Summary 68 68 + 69 69 + | AC ID | Description | Category | Phase | Verification Platform | 70 70 + |---|---|---|---|---| 71 71 + | AC1.1 | `nix flake show` lists `packages.x86_64-linux.docker-image` | Human (CI-automatable on Linux) | Phase 2, Step 8 | Linux | 72 72 + | AC1.2 | `nix flake show` lists `packages.aarch64-linux.docker-image` | Human (CI-automatable on Linux) | Phase 2, Step 8 | Linux | 73 73 + | AC1.3 | `docker-image` absent for Darwin systems | Automated | Phase 1, Task 3 / Phase 2, Step 7 | Any (macOS or Linux) | 74 74 + | AC2.1 | `nix build .#docker-image` succeeds on x86_64-linux | Human | Phase 2, Step 1 | x86_64-linux | 75 75 + | AC2.2 | `nix build .#packages.aarch64-linux.docker-image` succeeds | Human | Phase 2, Step 2 | aarch64-linux (or x86_64-linux with binfmt) | 76 76 + | AC2.3 | `docker load < result` succeeds | Human | Phase 2, Step 3 | Linux (Docker daemon) | 77 77 + | AC2.4 | `docker images` shows `relay:latest` | Human | Phase 2, Step 3 | Linux (Docker daemon) | 78 78 + | AC3.1 | `docker run --rm relay:latest` exits without linker errors | Human | Phase 2, Step 4 | Linux (Docker daemon) | 79 79 + | AC3.2 | `docker inspect` shows `SSL_CERT_FILE` env var | Human | Phase 2, Step 5 | Linux (Docker daemon) | 80 80 + | AC3.3 | `docker inspect` shows `TZDIR` env var | Human | Phase 2, Step 5 | Linux (Docker daemon) | 81 81 + | AC3.4 | `nix/docker.nix` tracked by git | Automated | Phase 1, Task 3 | Any | 82 82 + | AC4.1 | Image size under 50 MB | Human | Phase 2, Step 6 | Linux (Docker daemon) | 83 83 + | AC5.1 | Relay is a stub; no HTTP server required | Human | Phase 2, Step 4 | Linux (Docker daemon) |

+108

docs/test-plans/2026-03-08-MM-66.md

··· 1 1 + # MM-66 Human Test Plan 2 2 + 3 3 + **Feature:** Docker image derived from Nix build 4 4 + **Implementation plan:** `docs/implementation-plans/2026-03-08-MM-66/` 5 5 + **Generated:** 2026-03-08 6 6 + 7 7 + ## Prerequisites 8 8 + 9 9 + - A Linux system (x86_64-linux or aarch64-linux) with: 10 10 + - Nix installed (with flakes enabled) 11 11 + - Docker daemon running 12 12 + - The repository checked out at commit `7bb5376fbec84feab775f57cb4c4d2fb02307686` or later 13 13 + - Run the automated checks first: `bash tests/verify-mm66.sh` — all checks must pass before proceeding 14 14 + 15 15 + ## Phase 1: Flake Output Verification (AC1.1, AC1.2) 16 16 + 17 17 + | Step | Action | Expected | 18 18 + |------|--------|----------| 19 19 + | 1.1 | Run `nix flake show --accept-flake-config 2>/dev/null \| grep docker-image` | Output includes a line showing `docker-image` under the `x86_64-linux` packages section (e.g., `docker-image: package 'docker-image.tar.gz'` nested under `packages` > `x86_64-linux`) | 20 20 + | 1.2 | Inspect the same output for `aarch64-linux` | Output includes a line showing `docker-image` under the `aarch64-linux` packages section | 21 21 + | 1.3 | Confirm no `docker-image` appears under `aarch64-darwin` or `x86_64-darwin` sections | No `docker-image` lines appear in Darwin system sections (cross-validates AC1.3 on Linux) | 22 22 + 23 23 + ## Phase 2: Image Build (AC2.1, AC2.2) 24 24 + 25 25 + | Step | Action | Expected | 26 26 + |------|--------|----------| 27 27 + | 2.1 | Run `nix build .#docker-image --accept-flake-config` on x86_64-linux | Command exits with status 0. A `result` symlink appears in the project root pointing to a path like `/nix/store/...-docker-image.tar.gz` | 28 28 + | 2.2 | Run `ls -lh result` | The file is a gzipped tarball (`.tar.gz`). Note the file size for later comparison with AC4.1 | 29 29 + | 2.3 | (If aarch64-linux or binfmt available) Run `nix build .#packages.aarch64-linux.docker-image --accept-flake-config` | Command exits with status 0. A `result` symlink appears for the aarch64 image. If no aarch64 system or binfmt is available, skip and note as untested | 30 30 + 31 31 + ## Phase 3: Image Load and Inspect (AC2.3, AC2.4) 32 32 + 33 33 + | Step | Action | Expected | 34 34 + |------|--------|----------| 35 35 + | 3.1 | Run `docker load < result` | Output contains `Loaded image: relay:latest` | 36 36 + | 3.2 | Run `docker images relay` | Output shows at least one row with REPOSITORY `relay` and TAG `latest` | 37 37 + 38 38 + ## Phase 4: Image Contents Validation (AC3.1, AC3.2, AC3.3) 39 39 + 40 40 + | Step | Action | Expected | 41 41 + |------|--------|----------| 42 42 + | 4.1 | Run `docker run --rm relay:latest` | Container exits. There must be NO errors like `no such file or directory` or `error while loading shared libraries: libsqlite3.so`. A non-zero exit code is acceptable because the relay binary is a stub with no configuration to connect to | 43 43 + | 4.2 | Run `docker inspect relay:latest \| grep -E 'SSL_CERT_FILE'` | Output shows an environment variable line containing `SSL_CERT_FILE=/nix/store/...-nss-cacert-.../etc/ssl/certs/ca-bundle.crt` (the exact Nix store hash will vary) | 44 44 + | 4.3 | Run `docker inspect relay:latest \| grep -E 'TZDIR'` | Output shows an environment variable line containing `TZDIR=/nix/store/...-tzdata-.../share/zoneinfo` (the exact Nix store hash will vary) | 45 45 + 46 46 + ## Phase 5: Image Size (AC4.1) 47 47 + 48 48 + | Step | Action | Expected | 49 49 + |------|--------|----------| 50 50 + | 5.1 | Run `docker images relay --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"` | The SIZE column shows a value under 50 MB. The image should be relatively small since it is a minimal Nix closure containing only the relay binary, sqlite, cacert, and tzdata | 51 51 + 52 52 + ## Phase 6: Scope Boundary (AC5.1) 53 53 + 54 54 + | Step | Action | Expected | 55 55 + |------|--------|----------| 56 56 + | 6.1 | Run `docker run --rm relay:latest` (same as step 4.1) | The container exits immediately. It does NOT attempt to start an HTTP server, listen on any port, or block waiting for connections. This confirms the relay is a packaging-only stub | 57 57 + | 6.2 | Run `docker run --rm -d relay:latest && sleep 2 && docker ps \| grep relay` | No running container appears in `docker ps` output — the relay exited immediately, confirming no long-running server process | 58 58 + 59 59 + ## End-to-End: Full Build-to-Run Pipeline 60 60 + 61 61 + **Purpose:** Validate the complete workflow a developer or CI system would follow to build and verify the Docker image from a clean state. 62 62 + 63 63 + 1. Start from a clean state: `docker rmi relay:latest 2>/dev/null; rm -f result` 64 64 + 2. Run automated checks: `bash tests/verify-mm66.sh` — verify exit code 0 65 65 + 3. Build the image: `nix build .#docker-image --accept-flake-config` 66 66 + 4. Verify the result symlink exists: `ls -lh result` 67 67 + 5. Load into Docker: `docker load < result` 68 68 + 6. Verify loaded: `docker images relay` — shows `relay:latest` 69 69 + 7. Run the container: `docker run --rm relay:latest` — exits without linker errors 70 70 + 8. Inspect environment: `docker inspect relay:latest | jq '.[0].Config.Env'` — shows both `SSL_CERT_FILE` and `TZDIR` 71 71 + 9. Check size: `docker images relay --format '{{.Size}}'` — under 50 MB 72 72 + 10. Clean up: `docker rmi relay:latest; rm -f result` 73 73 + 74 74 + **Expected:** All steps succeed. The pipeline demonstrates that the Nix flake produces a valid, loadable, runnable Docker image with correct environment configuration and acceptable size. 75 75 + 76 76 + ## Human Verification Required 77 77 + 78 78 + | Criterion | Why Manual | Steps | 79 79 + |-----------|-----------|-------| 80 80 + | AC1.1 | Requires Linux Nix evaluation to confirm x86_64-linux output is present | Phase 1, Step 1.1 | 81 81 + | AC1.2 | Requires Linux Nix evaluation to confirm aarch64-linux output is present | Phase 1, Step 1.2 | 82 82 + | AC2.1 | `nix build` of docker-image only works on Linux; macOS has no `docker-image` output | Phase 2, Step 2.1 | 83 83 + | AC2.2 | Requires aarch64-linux system or binfmt QEMU support for cross-arch build | Phase 2, Step 2.3 | 84 84 + | AC2.3 | Requires Docker daemon to load the image tarball | Phase 3, Step 3.1 | 85 85 + | AC2.4 | Requires Docker daemon to list loaded images | Phase 3, Step 3.2 | 86 86 + | AC3.1 | Requires Docker daemon to run the container and verify no linker errors | Phase 4, Step 4.1 | 87 87 + | AC3.2 | Requires Docker daemon to inspect image config for SSL_CERT_FILE | Phase 4, Step 4.2 | 88 88 + | AC3.3 | Requires Docker daemon to inspect image config for TZDIR | Phase 4, Step 4.3 | 89 89 + | AC4.1 | Requires Docker daemon to check loaded image size | Phase 5, Step 5.1 | 90 90 + | AC5.1 | Requires Docker daemon to confirm relay is a stub (exits immediately, no server) | Phase 6, Steps 6.1-6.2 | 91 91 + 92 92 + ## Traceability 93 93 + 94 94 + | Acceptance Criterion | Automated Test | Manual Step | 95 95 + |----------------------|----------------|-------------| 96 96 + | AC1.1 | — | Phase 1, Step 1.1 | 97 97 + | AC1.2 | — | Phase 1, Step 1.2 | 98 98 + | AC1.3 | `tests/verify-mm66.sh` lines 16-51 | Phase 1, Step 1.3 (cross-validation) | 99 99 + | AC2.1 | — | Phase 2, Step 2.1 | 100 100 + | AC2.2 | — | Phase 2, Step 2.3 | 101 101 + | AC2.3 | — | Phase 3, Step 3.1 | 102 102 + | AC2.4 | — | Phase 3, Step 3.2 | 103 103 + | AC3.1 | — | Phase 4, Step 4.1 | 104 104 + | AC3.2 | — | Phase 4, Step 4.2 | 105 105 + | AC3.3 | — | Phase 4, Step 4.3 | 106 106 + | AC3.4 | `tests/verify-mm66.sh` lines 56-65 | — | 107 107 + | AC4.1 | — | Phase 5, Step 5.1 | 108 108 + | AC5.1 | — | Phase 6, Steps 6.1-6.2 |

+2

flake.nix

··· 48 48 in { 49 49 inherit relay; 50 50 default = relay; 51 51 + } // pkgs.lib.optionalAttrs pkgs.stdenv.isLinux { 52 52 + docker-image = import ./nix/docker.nix { inherit pkgs relay; }; 51 53 } 52 54 ); 53 55

+18

nix/docker.nix

··· 1 1 + { pkgs, relay }: 2 2 + pkgs.dockerTools.buildLayeredImage { 3 3 + name = "relay"; 4 4 + tag = "latest"; 5 5 + contents = [ 6 6 + relay 7 7 + pkgs.sqlite.out # runtime shared library only; .out excludes headers/dev outputs 8 8 + pkgs.cacert 9 9 + pkgs.tzdata 10 10 + ]; 11 11 + config = { 12 12 + Entrypoint = [ "${relay}/bin/relay" ]; 13 13 + Env = [ 14 14 + "SSL_CERT_FILE=${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt" 15 15 + "TZDIR=${pkgs.tzdata}/share/zoneinfo" 16 16 + ]; 17 17 + }; 18 18 + }

+81

tests/verify-mm66.sh

··· 1 1 + #!/usr/bin/env bash 2 2 + 3 3 + set -euo pipefail 4 4 + 5 5 + PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" 6 6 + cd "$PROJECT_ROOT" 7 7 + 8 8 + echo "==================================================" 9 9 + echo "MM-66 Automated Verification Tests" 10 10 + echo "==================================================" 11 11 + echo 12 12 + 13 13 + FAILED=0 14 14 + 15 15 + # AC1.3: Verify docker-image is absent for Darwin systems, present for Linux. 16 16 + # 17 17 + # Uses `nix eval` to inspect package attribute names per system — structurally 18 18 + # reliable and avoids parsing `nix flake show` tree output with brittle grep -A 19 19 + # heuristics. --accept-flake-config activates the Cachix binary cache; without 20 20 + # it, evaluation on a cold machine may trigger a 20+ minute build. 21 21 + echo "AC1.3: Checking docker-image platform availability..." 22 22 + 23 23 + DARWIN_PACKAGES=$(nix eval --json --accept-flake-config ".#packages.aarch64-darwin" --apply 'builtins.attrNames') 24 24 + if echo "$DARWIN_PACKAGES" | grep -q "docker-image"; then 25 25 + echo " FAIL: docker-image incorrectly present on aarch64-darwin" 26 26 + FAILED=1 27 27 + else 28 28 + echo " PASS: docker-image absent from aarch64-darwin" 29 29 + fi 30 30 + 31 31 + LINUX_PACKAGES=$(nix eval --json --accept-flake-config ".#packages.x86_64-linux" --apply 'builtins.attrNames') 32 32 + if echo "$LINUX_PACKAGES" | grep -q "docker-image"; then 33 33 + echo " PASS: docker-image present on x86_64-linux" 34 34 + else 35 35 + echo " FAIL: docker-image missing from x86_64-linux" 36 36 + FAILED=1 37 37 + fi 38 38 + 39 39 + echo 40 40 + 41 41 + # AC3.4: Verify nix/docker.nix is tracked by git. 42 42 + echo "AC3.4: Checking nix/docker.nix git tracking..." 43 43 + 44 44 + if git ls-files nix/docker.nix | grep -q "nix/docker.nix"; then 45 45 + echo " PASS: nix/docker.nix is tracked by git" 46 46 + else 47 47 + echo " FAIL: nix/docker.nix is not tracked by git" 48 48 + FAILED=1 49 49 + fi 50 50 + 51 51 + echo 52 52 + 53 53 + # Docker smoke test (Linux only — docker-image is not exposed on Darwin). 54 54 + # Runs when Docker is available and relay:latest is already loaded, confirming 55 55 + # the relay binary and libsqlite3.so are present in the image closure. The relay 56 56 + # is a stub and may exit non-zero; that is acceptable. Only linker/missing-file 57 57 + # errors indicate a broken image. 58 58 + if command -v docker >/dev/null 2>&1 && docker image inspect relay:latest >/dev/null 2>&1; then 59 59 + echo "Docker smoke test: relay:latest found — verifying binary and dynamic linking..." 60 60 + OUTPUT=$(docker run --rm relay:latest 2>&1 || true) 61 61 + if echo "$OUTPUT" | grep -qE "no such file|error while loading shared libraries"; then 62 62 + echo " FAIL: linker or missing-binary error detected" 63 63 + echo " $OUTPUT" 64 64 + FAILED=1 65 65 + else 66 66 + echo " PASS: relay:latest ran without linker or missing-binary errors" 67 67 + fi 68 68 + echo 69 69 + fi 70 70 + 71 71 + # Summary 72 72 + echo "==================================================" 73 73 + if [ $FAILED -eq 0 ]; then 74 74 + echo "Result: ALL CHECKS PASSED" 75 75 + echo "==================================================" 76 76 + exit 0 77 77 + else 78 78 + echo "Result: SOME CHECKS FAILED" 79 79 + echo "==================================================" 80 80 + exit 1 81 81 + fi