From 745f4d6fb4791d887855665da833d1a295588a1d Mon Sep 17 00:00:00 2001 From: beatzaplenty Date: Mon, 20 Jul 2026 02:58:25 +1000 Subject: [PATCH] Refresh stale architecture docs CLAUDE.md's "Composition pattern" section still described the pre-refactor layout (hosts//configuration.nix as a thin imports list, hardware-configuration wired in from flake.nix) from before the platform x build-type matrix landed. Rewrite it to match the current mkTarget/host.nix architecture and the module moves from the prior commit. Also fixes docs/nix-cache.md, which referenced a modules/nix/ path that never existed in this repo. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01La55Nsss8jZ7ZuzUV9mfot --- CLAUDE.md | 84 +++++++++++++++++++++++++++++------------------ docs/nix-cache.md | 4 +-- 2 files changed, 54 insertions(+), 34 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 818e2e5..7f7f9bd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -52,56 +52,76 @@ There is no test suite — "correctness" here means the flake evaluates and ## Architecture -`flake.nix` is the single entry point. It defines one `nixosConfigurations.` -attribute per machine, each built the same way: +`flake.nix` is the single entry point. It generates one +`nixosConfigurations.-` attribute per target via the +`mkTarget` function, composed from: ``` nixosSystem { modules = [ disko.nixosModules.disko - ./hosts//configuration.nix # host-specific config - ./modules/hardware-configuration/vm/.nix + sops-nix.nixosModules.sops + ./modules/common/configuration.nix + ./modules/platforms/${platform}.nix # what it runs on + ./modules/build-types/${buildType}.nix # what it's for + hostPath # hosts//host.nix — per-machine identity home-manager.nixosModules.home-manager { ... } - ]; + ] ++ (client-only modules, for every buildType except "nix-cache" itself) } ``` -Hosts currently defined in `flake.nix`: `nixos`, `docker`, `server`, -`nix-cache`, `nix-minimal`, `pxe-boot`, `linode-minimal`. Treat `flake.nix` as -the source of truth for which hosts exist — `README.md`, `AGENTS.md`, +Platforms: `linode`, `proxmox`, `lxc`. Build types: `minimal`, `nix-cache`, +`server`, `docker`, `gui`, `pxe-boot`. Not every combination is built — e.g. +`pxe-boot` has no `linode` variant (PXE/DHCP/TFTP need LAN L2 adjacency a +Linode VPS doesn't have). Treat `flake.nix`'s `generatedTargets` as the source +of truth for which hosts exist — `README.md`, `AGENTS.md`, `docs/flake-lock-automation.md`, and the CI eval workflows (`.github/workflows/check-nixos.yml`, `.gitea/workflows/check-nixos.yml`) list -hosts by hand and can drift from it, so re-check them against `flake.nix` when -adding or removing a host. +hosts by hand (or, for the CI workflows, evaluate the flake dynamically) and +can drift from it, so re-check them against `flake.nix` when adding or +removing a host. ### Composition pattern -Every host's real configuration lives in `hosts//configuration.nix`, -which is a thin list of `imports` pulling in reusable pieces from `modules/`: - -- `modules/common/configuration.nix` — base NixOS config imported by (almost) - every host: locale, users, nix settings, git. Nearly always the first import. -- `modules/common/home.nix` / `hosts//home.nix` — Home Manager config for - the `nixos` user; the `nixos` workstation has its own, other hosts share - `modules/common/home.nix`. +- `hosts//host.nix` — per-machine identity **only**: hostname, hostId, + per-machine secrets, `system.stateVersion`. These files carry no `imports` + of their own beyond narrow parameterized helpers (see + `modules/beszel/host-token.nix` below) — all shared behavior comes from the + platform/build-type modules composed in `flake.nix`, not from the host file. +- `modules/platforms/{linode,proxmox,lxc}.nix` — platform-specific config: + boot method, guest tooling, and (for linode/proxmox) the hypervisor-specific + hardware config, imported directly by the platform module itself + (`../hardware-configuration/vm/{proxmox,linode}.nix`) — **not** wired in + from `flake.nix`. `lxc.nix` has no hardware-configuration counterpart since + containers share the host kernel. +- `modules/build-types/*.nix` — what a system is for: + minimal/server/docker/gui/pxe-boot/nix-cache. +- `modules/common/configuration.nix` — base NixOS config imported by every + host: locale, users, nix settings, git. +- `modules/common/home.nix` / `hosts/nixos/home.nix` — Home Manager config for + the `nixos` user; the `nixos` workstation (`gui` build type) has its own, + other hosts share `modules/common/home.nix`. - `modules/disko/proxmox.nix` — declarative disk layout (GPT: ESP + swap + ext4 root) via disko, used by all Proxmox-VM hosts. - `modules/boot/efi.nix` — systemd-boot + EFI vars, paired with the disko module. -- `modules/hardware-configuration/vm/{proxmox,linode}.nix` — hypervisor-specific - hardware config, wired in from `flake.nix` (not from the host file). -- `modules/nix-cache/{client,server}.nix` + `modules/remote-builder-client.nix` — - binary cache substituter + SSH remote-builder wiring; see `docs/nix-cache.md` - for the full design (per-host local stores, no shared `/nix/store`, and how - the `nixremote` signing/SSH keys fit together). -- `modules/tailscale/`, `modules/docker/`, `modules/beszel/`, - `modules/services/*` — single-purpose, single-host feature modules (e.g. - `docker/enable-service.nix`, `services/zfs/enable-service.nix`, - `beszel/enable-agent.nix` for monitoring). Grep `hosts/*/configuration.nix` - for the `imports` list to see which modules apply to a given host. +- `modules/nix-cache/{client,server,remote-builder-client}.nix` — binary cache + substituter + SSH remote-builder wiring; see `docs/nix-cache.md` for the + full design (per-host local stores, no shared `/nix/store`, and how the + `nixremote` signing/SSH keys fit together). +- `modules/beszel/host-token.nix` — parameterized helper module + (`{ name, sopsFile }`) that wires a host's beszel-agent sops secret/template + and `environmentFile`; used by `hosts/server/host.nix` and + `hosts/nix-cache/host.nix` to avoid duplicating that boilerplate. +- `modules/tailscale/`, `modules/docker/`, `modules/networking/`, + `modules/traefik/`, `modules/services/*` — single-purpose, single-host + feature modules (e.g. `docker/enable-service.nix`, + `services/zfs/enable-service.nix`). Grep `modules/build-types/*.nix` for + each build type's `imports` list to see which modules apply where. -New host = new `hosts//configuration.nix` + a matching block added to -`flake.nix`'s `nixosConfigurations`, composed from existing `modules/*` pieces -rather than duplicating config. +New host = new `hosts//host.nix` + a matching +`mkTarget { platform; buildType; hostPath; }` entry added to `flake.nix`'s +`generatedTargets`, composed from existing `modules/*` pieces rather than +duplicating config. ### Other docs worth reading before touching these areas diff --git a/docs/nix-cache.md b/docs/nix-cache.md index ccdb36d..ad2b1a4 100644 --- a/docs/nix-cache.md +++ b/docs/nix-cache.md @@ -8,8 +8,8 @@ This repository configures `nix-cache` as a **binary cache server** and a **remo - Every machine still keeps and uses its own local `/nix/store`. - Clients prefer `http://nix-cache` for substitutes and keep `https://cache.nixos.org/` as fallback. - Clients can offload builds to `nix-cache` through SSH (`nix.distributedBuilds`). -- Client hosts import `modules/nix/cache-client.nix` and, when remote building is enabled, `modules/nix/remote-builder-client.nix`. -- The `nix-cache` host imports `modules/nix/cache-server.nix`. +- Client hosts import `modules/nix-cache/client.nix` and, when remote building is enabled, `modules/nix-cache/remote-builder-client.nix`. +- The `nix-cache` host imports `modules/nix-cache/server.nix`. ## Binary cache signing keys (on nix-cache)