docs: repo layout, module catalogue, host READMEs, stale-path fixes #56
@@ -12,16 +12,67 @@ Defined in the host table in [`flake.nix`](./flake.nix):
|
|||||||
| `lyrathorpe-mbp` | `aarch64-linux` | MacBook Pro (Apple Silicon, Asahi) |
|
| `lyrathorpe-mbp` | `aarch64-linux` | MacBook Pro (Apple Silicon, Asahi) |
|
||||||
| `lyrathorpe-t400` | `x86_64-linux` | ThinkPad T400 — [install notes](./hosts/T400/README.md) |
|
| `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) |
|
| `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-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),
|
Shared layers: `home` (home-manager: shell, git, editor),
|
||||||
`modules/common-nixos.nix` (all NixOS hosts: fonts, nix-ld, caches),
|
`modules/common-nixos.nix` (all NixOS hosts: fonts, nix-ld, caches),
|
||||||
`modules/workstation.nix` (physical graphical hosts: audio, thermald,
|
`modules/workstation.nix` (physical graphical hosts: audio, thermald,
|
||||||
earlyoom, fwupd), `modules/laptop.nix` (laptops: Wi-Fi, Bluetooth, power,
|
earlyoom, fwupd), `modules/laptop.nix` (laptops: Wi-Fi, Bluetooth, power,
|
||||||
lid), and `modules/ssh.nix` (key-only sshd). The x86 hosts also pull
|
lid), `modules/desktop.nix` (wired desktops: NetworkManager), and
|
||||||
`nixos-hardware` profiles.
|
`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/<Name>/ # 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/<Name>/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
|
## 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
|
identity into that user's home config as the `identity` module arg. A host can
|
||||||
therefore declare any number of users.
|
therefore declare any number of users.
|
||||||
|
|
||||||
|
Per-user home extras live under `users/<name>/`:
|
||||||
|
|
||||||
|
- [`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)
|
### Portable home (off-NixOS / external consumers)
|
||||||
|
|
||||||
The home config is also exposed for use beyond these hosts:
|
The home config is also exposed for use beyond these hosts:
|
||||||
@@ -61,6 +122,36 @@ sudo nixos-rebuild switch --flake .#<configuration>
|
|||||||
darwin-rebuild switch --flake .#lyrathorpe-mac
|
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/<Name>/`.** 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 .#<configuration>` 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
|
## Shell environment & keybindings
|
||||||
|
|
||||||
- Interactive shell features (zsh, tmux, git, ssh, CLI tools, auto-tmux):
|
- 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`
|
[`.gitea/workflows/ci.yaml`](./.gitea/workflows/ci.yaml) runs `nix flake check`
|
||||||
(formatting, `deadnix`, `statix`, the pre-commit hooks) and evaluates every
|
(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.
|
||||||
|
|||||||
Reference in New Issue
Block a user