From a857365cc32a4108109df3d80b1aa1381d1ab209 Mon Sep 17 00:00:00 2001 From: lyrathorpe Date: Mon, 6 Jul 2026 15:26:59 +0100 Subject: [PATCH] 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.