An easy-to-host PDS on the ATProtocol, iPhone and MacOS. Maintain control of your keys and data, always.
1# Nix Packaging and Deployment
2
3Last verified: 2026-03-09
4
5## Purpose
6Provides Nix-native build outputs (binary, container image) and a NixOS module
7for declarative relay deployment. Keeps all Nix packaging logic out of the
8top-level flake.nix.
9
10## Contracts
11
12### module.nix (NixOS module)
13- **Exposes**: `services.ezpds` option namespace (enable, package, configFile, settings.*)
14- **Guarantees**:
15 - `settings.*` options generate a Nix-store TOML config passed via `--config`
16 - `configFile` overrides all `settings.*` — when set, generated TOML is not used (escape hatch for agenix/sops-nix secret injection)
17 - `database_url = null` is omitted from generated TOML (relay derives path from data_dir)
18 - `public_url` is required; evaluation fails if unset
19 - Dedicated `ezpds` system user/group created automatically
20 - systemd service runs with hardening: ProtectSystem=strict, ProtectHome, NoNewPrivileges, PrivateTmp
21 - StateDirectory "ezpds" managed by systemd (mode 0750)
22 - ReadWritePaths always includes cfg.settings.data_dir — required when data_dir is not /var/lib/ezpds, since ProtectSystem=strict blocks writes elsewhere
23- **Expects**: Caller provides `services.ezpds.settings.public_url` (or a complete `configFile`)
24
25### docker.nix
26- **Exposes**: Called by flake.nix to produce `packages.<system>.docker-image`
27- **Guarantees**: Produces an OCI image tarball loadable via `docker load`
28- **Expects**: Linux builder (not exposed on macOS)
29
30## Dependencies
31- **Uses**: `crates/relay/` binary (via `packages.<system>.relay`)
32- **Used by**: flake.nix (imports module.nix, calls docker.nix)
33
34## Key Decisions
35- `lib.types.str` for paths (data_dir, configFile): avoids Nix store coercion of runtime paths
36- configFile escape hatch: secrets must not land in world-readable Nix store
37- systemd hardening on by default: defense-in-depth for a network-facing service
38
39## Invariants
40- module.nix must remain a standalone NixOS module importable without the flake
41- ExecStart always passes `--config <path>` (never bare invocation)
42
43## Key Files
44- `module.nix` - NixOS module for relay deployment
45- `docker.nix` - Docker image builder