Add documentation for NixOS and Home Manager conventions

2026-06-06 03:26:19 -03:00
parent 380b428d9a
commit d05212ffd3
2 changed files with 152 additions and 0 deletions
@@ -0,0 +1,47 @@
+# chiasson-nix
+
+My personal NixOS + Home Manager flake. [flake.nix](../flake.nix) feeds `./modules` through flake-parts and [import-tree](https://github.com/vic/import-tree) so config stays in small files instead of one monster module.
+
+How to work on it: [conventions.md](./conventions.md).
+
+## Hosts
+
+| Host | What it is |
+|------|------------|
+| `t2mbp` | Intel MacBook with T2 chip — Niri/DMS, `t2linux` + fan daemon |
+| `14900k` | Main x86 desktop — same GUI stack, also cross-builds aarch64 and exports NFS for Jellyfin |
+| `ideapad` | Lenovo IdeaPad Duet 3 (Chromebook, `lenovo-wormdingler`) — Mobile NixOS on Snapdragon, Niri/DMS, touch/tablet bits in `_private/` |
+| `uConsole` | Clockwork Pi uConsole (Pi 5 CM) — Niri/DMS, built with `nixos-raspberrypi` + oom-hardware |
+| `nix-server` | Headless x86 VM — Attic, Gitea, Immich, SwiftShare, Personal-Website, DDRM, Portainer, … |
+| `r5500` | Headless media box — Jellyfin, *arr, qBittorrent, Dispatcharr; library on NFS from `nix-server` |
+
+Each machine: `modules/hosts/<name>/default.nix` → `nixosConfigurations.<name>`, real config in `*Configuration` + optional `_private/` and `_services/`.
+
+## Deploy / rebuild
+
+Remote builds use the `builder` user (`systemDeployBuilder`, wired through `client-services` on desktops).
+
+Fleet deploy is [Navi](https://github.com/cafkafk/navi) — config in `modules/deploy/navi.nix`, outputs `flake.navi` / `flake.naviHive`.
+
+```bash
+nix develop          # devShell has navi + hints
+navi apply --on <host>
+navi apply-local --node 14900k --sudo   # this machine, if hostname matches
+```
+
+Plain rebuild still works: `sudo nixos-rebuild switch --flake .#<host>`.
+
+## Repo layout
+
+```
+modules/
+  hosts/<host>/     # per-machine composition
+  system/           # nixosModules.system aggregate
+  desktop/          # GUI stack
+  wisdom/           # HM modules (exports still named wisdom*)
+  ssh/              # inbound NixOS + outbound HM
+  deploy/           # navi hive
+  lib/              # pure helpers → flake.lib
+```
+
+Machine-only stuff lives in `hosts/<host>/_private/` — import-tree skips `_private/` globally, so those files only get pulled in where you import them.