malpercio.dev
An easy-to-host PDS on the ATProtocol, MacOS. Grandma-approved.
docs: add MM-66 Docker image design plan
Completed brainstorming session. Design includes:
- nix/docker.nix as { pkgs, relay }: function using buildLayeredImage
- flake.nix extended with optionalAttrs isLinux for docker-image output
- Linux-only outputs (x86_64-linux + aarch64-linux); Darwin excluded
- 2 implementation phases
+141
+141
docs/design-plans/2026-03-08-MM-66.md
+141
docs/design-plans/2026-03-08-MM-66.md
···
1
+
# MM-66: Docker Image Derived from Nix Build
2
+
3
+
## Summary
4
+
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
+
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
+
9
+
## Definition of Done
10
+
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
+
13
+
## Acceptance Criteria
14
+
15
+
### MM-66.AC1: docker-image outputs exist in the flake
16
+
- **MM-66.AC1.1 Success:** `nix flake show --accept-flake-config` (on Linux) lists `packages.x86_64-linux.docker-image`
17
+
- **MM-66.AC1.2 Success:** `nix flake show --accept-flake-config` (on Linux) lists `packages.aarch64-linux.docker-image`
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
+
20
+
### MM-66.AC2: Image builds and loads
21
+
- **MM-66.AC2.1 Success:** `nix build .#docker-image --accept-flake-config` completes without error on x86_64-linux
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
+
- **MM-66.AC2.3 Success:** `docker load < result` completes without error
24
+
- **MM-66.AC2.4 Success:** `docker images` shows `relay:latest` after loading
25
+
26
+
### MM-66.AC3: Image contents
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
+
- **MM-66.AC3.2 Success:** `docker inspect relay:latest` shows `SSL_CERT_FILE` env var pointing to a cacert store path
29
+
- **MM-66.AC3.3 Success:** `docker inspect relay:latest` shows `TZDIR` env var pointing to a tzdata store path
30
+
- **MM-66.AC3.4 Success:** `nix/docker.nix` exists and is tracked by git (`git ls-files nix/docker.nix` returns it)
31
+
32
+
### MM-66.AC4: Image size
33
+
- **MM-66.AC4.1 Success:** `docker images relay` shows image size under 50 MB
34
+
35
+
### MM-66.AC5: Scope boundaries
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
+
38
+
## Glossary
39
+
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
+
- **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
+
- **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
+
- **`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
+
- **`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
+
- **`pkgs.stdenv.isLinux`**: A boolean in nixpkgs that is `true` when the package set is being evaluated for a Linux target system.
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
+
- **`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
+
- **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
+
- **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
+
- **`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
+
- **`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
+
- **`tzdata`** (`pkgs.tzdata`): A nixpkgs package containing the IANA timezone database. Required at runtime for any Rust code that resolves timezone names.
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
+
- **`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
+
- **`cargoArtifacts`**: Crane's name for the pre-built dependency artifact set produced by `buildDepsOnly`. Passed into `buildPackage` so incremental rebuilds skip recompiling dependencies.
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
+
- **`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.
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
+
60
+
## Architecture
61
+
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
+
64
+
```
65
+
repo root/
66
+
├── flake.nix # extend forEachSystem — add docker-image on Linux
67
+
└── nix/
68
+
└── docker.nix # new — buildLayeredImage derivation
69
+
```
70
+
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
+
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
+
75
+
The resulting new flake outputs:
76
+
- `packages.x86_64-linux.docker-image`
77
+
- `packages.aarch64-linux.docker-image`
78
+
79
+
**Image contents:**
80
+
81
+
| Derivation | Purpose |
82
+
|---|---|
83
+
| `relay` | The crane-built binary; store path used as `Entrypoint` |
84
+
| `pkgs.sqlite.out` | Runtime `libsqlite3.so`; `.out` output carries shared libraries, not headers |
85
+
| `pkgs.cacert` | Mozilla CA bundle; referenced via `SSL_CERT_FILE` env var |
86
+
| `pkgs.tzdata` | IANA timezone database; referenced via `TZDIR` env var |
87
+
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
+
90
+
**Build workflow on Linux:**
91
+
```bash
92
+
nix build .#docker-image --accept-flake-config # produces ./result
93
+
docker load < result # loads relay:latest
94
+
docker run --rm relay:latest
95
+
```
96
+
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
+
99
+
## Existing Patterns
100
+
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
+
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
+
105
+
## Implementation Phases
106
+
107
+
<!-- START_PHASE_1 -->
108
+
### Phase 1: Write derivation files
109
+
**Goal:** Create `nix/docker.nix` and extend `flake.nix` so the docker-image output is exposed on Linux.
110
+
111
+
**Components:**
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
+
- `flake.nix` — extend the `forEachSystem` return value with `// pkgs.lib.optionalAttrs pkgs.stdenv.isLinux { docker-image = import ./nix/docker.nix { inherit pkgs relay; }; }`
114
+
115
+
**Dependencies:** None (MM-65 relay build is already in `flake.nix`)
116
+
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
+
<!-- END_PHASE_1 -->
119
+
120
+
<!-- START_PHASE_2 -->
121
+
### Phase 2: Build verification
122
+
**Goal:** Confirm the image builds, loads, and runs on Linux; verify size target.
123
+
124
+
**Components:**
125
+
- CI or Linux shell verification: `nix build .#docker-image --accept-flake-config` succeeds
126
+
- `docker load < result` loads without error; `docker images` shows `relay:latest`
127
+
- `docker run --rm relay:latest` exits (relay is currently a stub)
128
+
- Image size reported by `docker images` is under 50 MB
129
+
130
+
**Dependencies:** Phase 1
131
+
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
+
<!-- END_PHASE_2 -->
134
+
135
+
## Additional Considerations
136
+
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
+
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
+
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.