From a857365cc32a4108109df3d80b1aa1381d1ab209 Mon Sep 17 00:00:00 2001 From: lyrathorpe Date: Mon, 6 Jul 2026 15:26:59 +0100 Subject: [PATCH 1/6] docs: add repo layout, module catalogue and add-a-host guide --- README.md | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 99 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index bb1a1bb..f8fefa3 100644 --- a/README.md +++ b/README.md @@ -12,16 +12,67 @@ Defined in the host table in [`flake.nix`](./flake.nix): | `lyrathorpe-mbp` | `aarch64-linux` | MacBook Pro (Apple Silicon, Asahi) | | `lyrathorpe-t400` | `x86_64-linux` | ThinkPad T400 — [install notes](./hosts/T400/README.md) | | `lyrathorpe-macpro31` | `x86_64-linux` | Mac Pro 3,1, desktop — [install notes](./hosts/MacPro31/README.md) | -| `emmathorpe-edaas` | `x86_64-linux` | Work WSL box (NixOS-WSL) | +| `emmathorpe-edaas` | `x86_64-linux` | Work WSL box (NixOS-WSL) — [notes](./hosts/EDaaS/README.md) | | `lyrathorpe-rpi5` | `aarch64-linux` | Raspberry Pi 5 headless server: Docker host + nginx reverse proxy — [install notes](./hosts/RPi5/README.md) | -| `lyrathorpe-mac` | `aarch64-darwin` | macOS (nix-darwin) | +| `lyrathorpe-mac` | `aarch64-darwin` | macOS (nix-darwin) — [notes](./hosts/Darwin/README.md) | Shared layers: `home` (home-manager: shell, git, editor), `modules/common-nixos.nix` (all NixOS hosts: fonts, nix-ld, caches), `modules/workstation.nix` (physical graphical hosts: audio, thermald, earlyoom, fwupd), `modules/laptop.nix` (laptops: Wi-Fi, Bluetooth, power, -lid), and `modules/ssh.nix` (key-only sshd). The x86 hosts also pull -`nixos-hardware` profiles. +lid), `modules/desktop.nix` (wired desktops: NetworkManager), and +`modules/ssh.nix` (key-only sshd). The x86 hosts also pull `nixos-hardware` +profiles. The full module catalogue is below. + +## Repository layout + +``` +flake.nix # inputs, mkHost/mkDarwinHost, the host tables, dev shell + checks +flake.lock # pinned input revisions (Renovate keeps this fresh) +modules/ # reusable NixOS system modules (see "Module catalogue") +home/ # home-manager profile: shell, git, editor, claude, desktop, sway +users/ # identity registry + per-user home extras (see "Users") +hosts// # per-machine config: configuration.nix + hardware-configuration.nix +lib/ # small pure helpers (currently the Catppuccin Mocha palette) +.gitea/workflows/ # CI (nix flake check + per-host eval) +statix.toml # lint config (house-style lints disabled) +.editorconfig # base whitespace style +tf-inspect/ # UNRELATED scratch project (gitignored, its own git repo); + # RouterOS / home-services Terraform, not part of this flake +``` + +Each `nixosConfiguration` / `darwinConfiguration` is assembled in `flake.nix` +from three layers: the shared `baseModules` (or `darwinBaseModules`), the +per-form-factor and `nixos-hardware` modules listed in the host table, and the +per-machine `hosts//configuration.nix`. Home-manager is wired in as a +system module; each user's home is composed from the `homeModules` list in that +host's table entry. + +## Module catalogue + +Reusable NixOS modules under [`modules/`](./modules). "Imported by" says how a +module reaches a host: **baseModules** (every NixOS host, via `flake.nix`), +**host table** (listed explicitly per host in `flake.nix`), or **transitively** +(pulled in by another module's `imports`). + +| Module | Imported by | What it does / when to use it | +| -------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `common-nixos.nix` | baseModules (all NixOS) | Timezone/locale, store hygiene (auto-optimise, big download buffer, **no** auto-GC), the nix-community binary cache, `nix-ld`, base CLI (`git`, `fastfetch`), and the fleet-wide font stack. | +| `users.nix` | baseModules (all NixOS) | Builds `users.users` from the registry for the host's `hostUsers`; enables zsh; enables Firefox + Thunderbird **only** when `features.swayDesktop.enable` is on. Applies per-user `linger`. | +| `features.nix` | baseModules (all NixOS) | Declares feature-flag options (currently `features.swayDesktop.enable`) so any host can read/set them without importing the heavy implementation module. | +| `workstation.nix` | transitively (via laptop/desktop) | Form-factor-agnostic base for physical graphical hosts: turns on `swayDesktop`, Dvorak console, PipeWire, firewall (default-deny), fstrim, earlyoom, fwupd, thermald (x86), redistributable fw. | +| `laptop.nix` | host table (MBP, T400) | `imports` workstation.nix, then adds the portable bits: iwd Wi-Fi, lid suspend/lock, Bluetooth + blueman. | +| `desktop.nix` | host table (Mac Pro) | `imports` workstation.nix, then swaps Wi-Fi for wired NetworkManager. Pair with `portable = false` in the host table. | +| `sway.nix` | host table (graphical hosts) | Implementation of `features.swayDesktop`: the system Sway package, the greetd/ReGreet (cage) greeter forced to Dvorak, xdg-portal, Wayland utility packages. Home-side Sway config is in `home/sway.nix`. | +| `ssh.nix` | host table (T400, Mac Pro, RPi5) | Enables sshd, opens port 22, enforces a key-only policy (no password / keyboard-interactive, no root). Authorized keys come from the registry via `users.nix`. | +| `firmware/` | referenced by MBP host config | Committed Apple peripheral firmware blobs for the Asahi MBP (see "MacBook (Asahi) firmware"). | + +Form-factor decision: a **laptop** imports `laptop.nix` (default +`portable = true`); a **wired desktop** imports `desktop.nix` and sets +`portable = false`; a **headless server** imports neither (leaves +`features.swayDesktop.enable` at its default `false`) and adds only what it +serves. `portable` is threaded through to `home/sway.nix`, which drops the +battery block and brightness keys on desktops. ## Users @@ -38,6 +89,16 @@ Identity is data, kept separate from the reusable modules: identity into that user's home config as the `identity` module arg. A host can therefore declare any number of users. +Per-user home extras live under `users//`: + +- [`users/lyrathorpe/home.nix`](./users/lyrathorpe/home.nix) — personal extras + (an ssh host shortcut, gammastep coordinates); imported on Lyra's hosts. +- [`users/emmathorpe/work.nix`](./users/emmathorpe/work.nix) — the work + toolchain (kubectl/helm/az/etc.), work-only LSP servers, and the corporate ssh + handling; imports + [`users/emmathorpe/renovate-review.nix`](./users/emmathorpe/renovate-review.nix), + the daily headless Renovate-PR review timer (EDaaS only). + ### Portable home (off-NixOS / external consumers) The home config is also exposed for use beyond these hosts: @@ -61,6 +122,36 @@ sudo nixos-rebuild switch --flake .# darwin-rebuild switch --flake .#lyrathorpe-mac ``` +On a host whose `networking.hostName` matches its flake attribute (the WSL box +and the Pi are set up this way), `nh os switch` resolves the configuration from +the hostname with no `--flake`/`-H` flag. + +## Adding a new host + +1. **Create `hosts//`.** Add `configuration.nix` with the host-specific + bits only: `networking.hostName`, bootloader (firmware-specific — it is + deliberately not set in the shared modules), and any per-machine hardware + quirks. Keep anything reusable in `modules/` instead. +2. **Hardware config.** Generate `hardware-configuration.nix` on the real + machine with `nixos-generate-config` and commit it. If the machine does not + exist yet, commit a clearly-labelled placeholder so the host still evaluates + in CI (see the existing T400 / RPi5 placeholders), and replace it at install. + These files are excluded from the formatter and linters. +3. **Add a host-table entry in `flake.nix`.** Under `hosts` (NixOS) or + `darwinHosts` (macOS), set `system`, the `modules` list (host config + form + factor + any `nixos-hardware` profiles), and the `users` map (each user's + `homeModules`). Choose the form factor per the decision note above; a headless + host imports neither `laptop.nix` nor `desktop.nix`. +4. **Users.** If the host introduces a new person, add them to + `users/registry.nix` first; otherwise reference an existing username. +5. **Verify.** `nix flake check` formats, lints, and evaluates every host — + including the new one — so a broken entry fails locally before CI. Then + `sudo nixos-rebuild switch --flake .#` on the machine. + +No change to CI is needed: the host-eval step discovers hosts from the flake +(`attrNames` of the configuration sets), so a new entry is picked up +automatically. + ## Shell environment & keybindings - Interactive shell features (zsh, tmux, git, ssh, CLI tools, auto-tmux): @@ -111,4 +202,7 @@ A dev shell and a formatting/lint gate are wired through the flake: [`.gitea/workflows/ci.yaml`](./.gitea/workflows/ci.yaml) runs `nix flake check` (formatting, `deadnix`, `statix`, the pre-commit hooks) and evaluates every -NixOS and Darwin host configuration on push/PR. +NixOS and Darwin host configuration on push/PR. It always runs (no `paths:` +filter) so the required check never hangs pending; the heavy Nix steps are +skipped when a PR touches no `.nix`/lockfile/workflow file, and the job still +reports green. From 574773de73222e002a53063f005b8d130fbe9a5c Mon Sep 17 00:00:00 2001 From: lyrathorpe Date: Mon, 6 Jul 2026 15:27:00 +0100 Subject: [PATCH 2/6] docs(edaas): add host README --- hosts/EDaaS/README.md | 53 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 hosts/EDaaS/README.md diff --git a/hosts/EDaaS/README.md b/hosts/EDaaS/README.md new file mode 100644 index 0000000..8d44c40 --- /dev/null +++ b/hosts/EDaaS/README.md @@ -0,0 +1,53 @@ +# Work WSL box — `emmathorpe-edaas` + +Flake host: `emmathorpe-edaas` (`x86_64-linux`). NixOS running under +**NixOS-WSL** on the corporate Windows machine. Headless: no Sway desktop +(`features.swayDesktop.enable = false`), plain WSL shell login. Files: +`configuration.nix`. + +## What this host is + +The day-to-day work environment. It layers the corporate Kubernetes / Helm / +Terraform / cloud toolchain and a couple of work-only editor language servers on +top of the shared home profile. The system config here is thin — it is mostly +WSL plumbing; the user-facing tooling lives in +[`../../users/emmathorpe/work.nix`](../../users/emmathorpe/work.nix). + +## WSL specifics + +- `wsl.enable`, default user `emmathorpe`, Windows PATH interop and start-menu + launchers on. `/etc/hosts` generation is off (`generateHosts = false`). +- **Docker Desktop integration**, not the native daemon as the primary path: + `wsl.extraBin` shims the coreutils/`groupadd`/`usermod` binaries Docker + Desktop's `wsl-distro-proxy` expects, and `docker-desktop-proxy.script` is + patched to the real proxy path. The native `virtualisation.docker` is also + enabled (with `enableOnBoot` + `autoPrune`). +- `programs.ssh.systemd-ssh-proxy.enable = false` — the NixOS-WSL store is a + read-only VHD owned by `nobody`, and OpenSSH rejects the generated + `ssh-proxy` Include as "Bad owner or permissions", which would break ssh/git + for every command. The vsock proxy it provides is unused under WSL. +- `networking.hostName = "emmathorpe-edaas"` matches the flake attribute so + `nh os switch` resolves without `-H`. + +## Renovate review timer + +The host-table entry sets `users.emmathorpe.linger = true` so the user's +`systemd --user` instance stays alive without an open login session. That keeps +the daily headless **Renovate PR review** timer firing — defined in +[`../../users/emmathorpe/renovate-review.nix`](../../users/emmathorpe/renovate-review.nix) +(imported only from `work.nix`, so it exists on this machine alone). See that +file's header for the auth (Vertex AI ADC), triage policy, and caveats. + +## stateVersion + +`system.stateVersion = "24.11"` — the release this box was first installed on. +Leave it; it freezes stateful defaults and is not meant to track the current +nixpkgs. + +## Apply + +```sh +sudo nixos-rebuild switch --flake .#emmathorpe-edaas +# or, since the hostname matches the attribute: +nh os switch +``` From f57d6ab1f958ae45fe344979bc602d93ae013411 Mon Sep 17 00:00:00 2001 From: lyrathorpe Date: Mon, 6 Jul 2026 15:27:01 +0100 Subject: [PATCH 3/6] docs(darwin): add host README --- hosts/Darwin/README.md | 51 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 hosts/Darwin/README.md diff --git a/hosts/Darwin/README.md b/hosts/Darwin/README.md new file mode 100644 index 0000000..dfd62d6 --- /dev/null +++ b/hosts/Darwin/README.md @@ -0,0 +1,51 @@ +# macOS (nix-darwin) — `lyrathorpe-mac` + +Flake host: `lyrathorpe-mac` (`aarch64-darwin`). Apple Silicon Mac managed by +**nix-darwin** from this same flake. Built via `mkDarwinHost` (single-user — +macOS owns the account; identity still comes from the registry). Files: +`configuration.nix`. + +## What this host is + +A macOS workstation. The interactive user environment (shell, git, editor, +Claude) is the **shared `../../home` bundle** — the same modules the Linux hosts +use — so the terminal experience matches. The Linux-only `desktop.nix`/`sway.nix` +are intentionally left out. This host config covers the macOS-specific layer: +system packages, Homebrew, and macOS UI defaults. + +## Package sourcing + +- **nixpkgs** (`environment.systemPackages`) for CLI tooling and libraries. +- **Homebrew**, owned declaratively by `nix-homebrew` (Rosetta enabled for + x86_64 formulae). The `brews`/`casks` lists are **authoritative**: + `onActivation.cleanup = "zap"` uninstalls anything not declared. GUI apps are + casks (nixpkgs darwin GUI support is unreliable); a few version-pinned + toolchains and the PWA host stay on brew for continuity. +- **Mac App Store** apps are **not** declarative: nix-darwin 26.05 runs + activation as root, and `mas` cannot reach the App Store session from root. + Install them by hand with `mas install ` from a GUI Terminal (the `mas` + CLI is in `environment.systemPackages`). + +## macOS integration + +- `security.pam.services.sudo_local` — **Touch ID for sudo** (and + `darwin-rebuild`'s sudo prompt), kept in `sudo_local` so it survives OS + updates. `reattach` pulls in `pam_reattach` so Touch ID works inside tmux + (which the terminals auto-start). +- `system.defaults` — declarative dock / finder / global / trackpad preferences, + applied on activation and reversible. This is the main reason to run nix-darwin + beyond package management. +- The JetBrainsMono Nerd Font is installed to `/Library/Fonts`; set it in + iTerm2 (Settings → Profiles → Text → Font) so the tmux statusline glyphs + render. + +## stateVersion + +`system.stateVersion = 5` (the nix-darwin state version, an integer — not a +NixOS release string). Read `darwin-rebuild changelog` before changing it. + +## Apply + +```sh +darwin-rebuild switch --flake .#lyrathorpe-mac +``` From 58c0004f208b743be74f7c83b25e55cd09210a17 Mon Sep 17 00:00:00 2001 From: lyrathorpe Date: Mon, 6 Jul 2026 15:27:02 +0100 Subject: [PATCH 4/6] docs(t400): fix stale module paths --- hosts/T400/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hosts/T400/README.md b/hosts/T400/README.md index 3480f30..1b51c42 100644 --- a/hosts/T400/README.md +++ b/hosts/T400/README.md @@ -35,7 +35,7 @@ change and `radeon` stays idle. ## Login Graphical login via a Wayland greeter — `greetd` running ReGreet inside the -`cage` kiosk compositor — configured centrally in `lyrathorpe/swaywm.nix` for +`cage` kiosk compositor — configured centrally in `../../modules/sway.nix` for every Sway host (gated on `features.swayDesktop.enable`). The greeter is forced to the Dvorak layout to match the console and Sway session. Set the user password (`passwd lyrathorpe`) after install, or the greeter cannot From 610d5d8b2840102a5fafe86bb8ebc896e9dfb31e Mon Sep 17 00:00:00 2001 From: lyrathorpe Date: Mon, 6 Jul 2026 15:27:02 +0100 Subject: [PATCH 5/6] docs(macpro31): fix stale module paths --- hosts/MacPro31/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hosts/MacPro31/README.md b/hosts/MacPro31/README.md index d223e5b..8b5ce00 100644 --- a/hosts/MacPro31/README.md +++ b/hosts/MacPro31/README.md @@ -48,7 +48,7 @@ gigabit ports. ## Login Graphical login via a Wayland greeter — `greetd` running ReGreet inside the -`cage` kiosk compositor — configured centrally in `lyrathorpe/swaywm.nix` for +`cage` kiosk compositor — configured centrally in `../../modules/sway.nix` for every Sway host (gated on `features.swayDesktop.enable`). The greeter is forced to the Dvorak layout to match the console and Sway session. Set the user password (`passwd lyrathorpe`) after install, or the greeter cannot From 819633260ef2d6bd151da516651487ea21e3fa90 Mon Sep 17 00:00:00 2001 From: lyrathorpe Date: Mon, 6 Jul 2026 15:27:03 +0100 Subject: [PATCH 6/6] docs(rpi5): fix stale module paths --- hosts/RPi5/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/hosts/RPi5/README.md b/hosts/RPi5/README.md index 5238292..04dcab3 100644 --- a/hosts/RPi5/README.md +++ b/hosts/RPi5/README.md @@ -15,7 +15,7 @@ Headless `aarch64-linux` server with two roles: ```sh nixos-generate-config --root /mnt # copy /mnt/etc/nixos/hardware-configuration.nix over - # system/machine/RPi5/hardware-configuration.nix in this repo, then commit + # hosts/RPi5/hardware-configuration.nix in this repo, then commit ``` `hardware-configuration.nix` in this directory is a **placeholder** committed only so the host evaluates in CI. The machine will not boot correctly until it @@ -28,7 +28,8 @@ Headless `aarch64-linux` server with two roles: nh os switch ``` 4. Give the login user a password (`passwd lyrathorpe`) and confirm the key in - `system/modules/ssh.nix` is the one you will connect with. + the user registry (`../../users/registry.nix`, applied by + `../../modules/ssh.nix`) is the one you will connect with. ## Docker socket (security)