An easy-to-host PDS on the ATProtocol, MacOS. Grandma-approved.
docs: update project context for NixOS module additions
Add Flake Outputs section and nix-check command to root CLAUDE.md.
Create nix/CLAUDE.md documenting module.nix contracts and docker.nix.
authored by
Tangled
562add74
8b08d6be
+53
-2
+9
-2
CLAUDE.md
+9
-2
CLAUDE.md
···
1
1
# ezpds
2
2
3
-
Last verified: 2026-03-08
3
+
Last verified: 2026-03-09
4
4
5
5
## Tech Stack
6
6
- Language: Rust (stable channel via rust-toolchain.toml)
···
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)
15
+
- `just nix-check` / `nix flake check --impure --accept-flake-config` - Validate NixOS module evaluation and flake structure
15
16
- `cargo build` - Build all crates
16
17
- `cargo test` - Run all tests
17
18
- `cargo clippy --workspace -- -D warnings` - Lint (warnings as errors)
···
31
32
- `crates/repo-engine/` - ATProto repo engine
32
33
- `crates/crypto/` - Cryptographic operations
33
34
- `crates/common/` - Shared types and utilities
34
-
- `nix/` - Nix build helpers (docker.nix produces the relay container image)
35
+
- `nix/` - Nix packaging and deployment (docker.nix: container image; module.nix: NixOS module)
35
36
- `docs/` - Specs, design plans, implementation plans
37
+
38
+
## Flake Outputs
39
+
- `packages.<system>.relay` - Relay binary
40
+
- `packages.<system>.docker-image` - Docker image tarball (Linux only)
41
+
- `nixosModules.default` - NixOS module exposing `services.ezpds` options (see `nix/CLAUDE.md`)
42
+
- `devShells.<system>.default` - Development shell via devenv
36
43
37
44
## Conventions
38
45
- Workspace-level dependency versions in root Cargo.toml; crates use `{ workspace = true }`
+44
nix/CLAUDE.md
+44
nix/CLAUDE.md
···
1
+
# Nix Packaging and Deployment
2
+
3
+
Last verified: 2026-03-09
4
+
5
+
## Purpose
6
+
Provides Nix-native build outputs (binary, container image) and a NixOS module
7
+
for declarative relay deployment. Keeps all Nix packaging logic out of the
8
+
top-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
+
- **Expects**: Caller provides `services.ezpds.settings.public_url` (or a complete `configFile`)
23
+
24
+
### docker.nix
25
+
- **Exposes**: Called by flake.nix to produce `packages.<system>.docker-image`
26
+
- **Guarantees**: Produces an OCI image tarball loadable via `docker load`
27
+
- **Expects**: Linux builder (not exposed on macOS)
28
+
29
+
## Dependencies
30
+
- **Uses**: `crates/relay/` binary (via `packages.<system>.relay`)
31
+
- **Used by**: flake.nix (imports module.nix, calls docker.nix)
32
+
33
+
## Key Decisions
34
+
- `lib.types.str` for paths (data_dir, configFile): avoids Nix store coercion of runtime paths
35
+
- configFile escape hatch: secrets must not land in world-readable Nix store
36
+
- systemd hardening on by default: defense-in-depth for a network-facing service
37
+
38
+
## Invariants
39
+
- module.nix must remain a standalone NixOS module importable without the flake
40
+
- ExecStart always passes `--config <path>` (never bare invocation)
41
+
42
+
## Key Files
43
+
- `module.nix` - NixOS module for relay deployment
44
+
- `docker.nix` - Docker image builder