From 68ea04f173ab757b0d27deb180195bfc277fe13a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?ryan4yin=20=7C=20=E4=BA=8C=E8=8A=B1?= Date: Fri, 2 Oct 2026 10:21:55 +0800 Subject: [PATCH] fix(docs): correct stale and mismatched documentation (#338) --- .agents/skills/nix-config-desktop/SKILL.md | 2 +- .agents/skills/nix-config-secrets/SKILL.md | 6 +-- README.md | 2 +- agents/install-cli.md | 7 ++- certs/README.md | 2 +- home/README.md | 2 +- home/base/README.md | 3 +- home/base/core/editors/helix/README.md | 46 +++++++++---------- home/base/core/editors/neovim/README.md | 8 ++-- home/base/tui/editors/README.md | 5 +- home/linux/gui/README.md | 3 +- home/linux/gui/base/README.md | 4 +- home/linux/gui/i3/README.md | 4 +- .../homelab-services/README.md | 4 ++ .../homelab-services/immich/README.md | 5 +- hosts/README.md | 11 +++-- hosts/idols-ai/README.md | 2 +- hosts/idols-ai/disko-fs-data.nix | 2 +- hosts/k8s/README.md | 5 +- infra/README.md | 6 +-- infra/rustfs/README.md | 2 +- lib/README.md | 11 +++-- modules/README.md | 5 +- nixos-installer/README.md | 8 +++- nixos-installer/README.shoukei.md | 5 +- outputs/README.md | 5 +- secrets/README.md | 25 ++++++---- vars/README.md | 5 +- 28 files changed, 111 insertions(+), 84 deletions(-) diff --git a/.agents/skills/nix-config-desktop/SKILL.md b/.agents/skills/nix-config-desktop/SKILL.md index 79edbc3f..8f2da969 100644 --- a/.agents/skills/nix-config-desktop/SKILL.md +++ b/.agents/skills/nix-config-desktop/SKILL.md @@ -121,7 +121,7 @@ What a screenshot cannot show: reload, not a broken startup. Do not "test" with commands that act on the session the user is looking at: `niri msg action quit`, -`niri msg action power-off-monitors`, `noctalia msg dpms-off`, `noctalia msg lock`. +`niri msg action power-off-monitors`, `noctalia msg dpms-off`, `noctalia msg session lock`. ## Why these rules exist diff --git a/.agents/skills/nix-config-secrets/SKILL.md b/.agents/skills/nix-config-secrets/SKILL.md index 5079d24e..feabdd26 100644 --- a/.agents/skills/nix-config-secrets/SKILL.md +++ b/.agents/skills/nix-config-secrets/SKILL.md @@ -41,7 +41,7 @@ recipient rule. | The pinned revision of that repository | `flake.lock`, input `mysecrets` | | Declaration: file, mode/owner, `/etc` copy | `secrets/nixos.nix`, `secrets/darwin.nix` | | Which host gets which group | `modules.secrets..enable` in `outputs//src/.nix` or a host module | -| Consumers | modules reading `/etc/agenix/` or `config.age.secrets."".path` | +| Consumers | modules reading `config.age.secrets."".path` (default `/run/agenix/`) | | Decryption key | `age.identityPaths`: the host's SSH host key; `/persistent/etc/ssh/...` on a preservation host | ## 2. Add or change a secret @@ -73,8 +73,8 @@ a root-owned copy readable. ## 4. Verify without reading ```bash -stat -c '%a %U:%G' /etc/agenix/ # mode and owner, not content -ls -l /etc/agenix/ +stat -c '%a %U:%G' /run/agenix/ # mode and owner, not content (the default path) +ls -l /run/agenix/ # /etc/agenix/ holds only the environment.etc copies journalctl -b | grep -5 agenix # NixOS tail -n 100 /Library/Logs/org.nixos.activate-agenix.stderr.log # macOS ``` diff --git a/README.md b/README.md index 211d472b..9f825175 100644 --- a/README.md +++ b/README.md @@ -107,7 +107,7 @@ See [./secrets](./secrets) for details. > [hardware-configuration.nix](hosts/idols-ai/hardware-configuration.nix), > [Nvidia support](hosts/idols-ai/hardware-nvidia.nix), etc.) which is not suitable for your > hardware, and requires my private secrets repository -> [ryan4yin/nix-secrets](https://github.com/ryan4yin/nix-config/tree/main/secrets) to deploy. You +> [ryan4yin/nix-secrets](https://github.com/ryan4yin/nix-secrets) to deploy. You > may use this repo as a reference to build your own configuration. Run `just --list` to see every recipe. diff --git a/agents/install-cli.md b/agents/install-cli.md index a7cfdba0..b5f539cb 100644 --- a/agents/install-cli.md +++ b/agents/install-cli.md @@ -19,8 +19,7 @@ Installed via Nix: npx ctx7 setup ``` -## Update npm-installed agent tools +## Update -```bash -npm update -g -``` +The agent CLIs come from Nix (`home/base/gui/dev-tools.nix`) through the `llm-agents` flake input, +so update them with the flake rather than npm. diff --git a/certs/README.md b/certs/README.md index 0de8666f..4bc66047 100644 --- a/certs/README.md +++ b/certs/README.md @@ -18,6 +18,6 @@ public certificates and configuration files are committed to this repository for ## Usage -Run `./gen-certs.sh` to generate new certificates using the ECC CA configuration. +Run `bash gen-certs.sh` to generate new certificates using the ECC CA configuration. See [../secrets](../secrets/) for the corresponding private key management. diff --git a/home/README.md b/home/README.md index 0e43e028..981e53ad 100644 --- a/home/README.md +++ b/home/README.md @@ -16,7 +16,7 @@ home/ │ │ └── ... │ ├── tui/ # Terminal/TUI applications │ │ ├── editors/ # Heavy editor/tooling pkgs only (`packages.nix`; core editors live under `core/editors`) -│ │ ├── encryption/ # GPG, password-store, etc. +│ │ ├── encryption/ # Encryption and security tooling │ │ └── ... │ └── home.nix # Main home manager entry point ├── linux/ # Linux-specific home manager configurations diff --git a/home/base/README.md b/home/base/README.md index 1cc2a79f..0b16775c 100644 --- a/home/base/README.md +++ b/home/base/README.md @@ -20,7 +20,8 @@ systems. - **theme.nix**: Color schemes and theming - **xdg.nix**: XDG base-directory configuration - **yazi.nix**: Terminal file manager configuration - - **zellij/**: Terminal multiplexer with custom layouts + - **zellij/**: Terminal multiplexer (enable + `zj` alias; config and layouts live in + `tui/zellij/`) ### Desktop Environment diff --git a/home/base/core/editors/helix/README.md b/home/base/core/editors/helix/README.md index 0c5efa2b..4db8e79d 100644 --- a/home/base/core/editors/helix/README.md +++ b/home/base/core/editors/helix/README.md @@ -84,32 +84,32 @@ selection, and `$` / `0` line jumps (see `home/base/core/editors/helix/default.n | Word-label jump | `gw` shows two-character labels; type a label to jump, `Esc` cancels | | Line / file | `Home` / `End`; `gg` start or goto line; `G` line | | Half / full page | `Ctrl-u` / `Ctrl-d`; `Ctrl-b` / `Ctrl-f` | -| Jumplist | `Ctrl-o` back, `Ctrl-i` forward; `Ctrl-s` save spot | +| Jumplist | `Ctrl-Shift-o` back, `Ctrl-i` forward; `Ctrl-s` save spot | ### Selection & changes -| Action | Keys / notes | -| ---------------------- | --------------------------------------------------------------------------- | -| Extend selections | `v` select mode; motions extend instead of moving; `v` or `Esc` leaves mode | -| Line selection | `x` extend line; `X` line bounds; repeat or use a count for more lines | -| Collapse selections | `;` collapse selections back to cursors | -| Select all / regex | `%`; `s` regex in selections; `S` split on regex | -| Multiple cursors | `C` duplicate to next suitable line; `Alt-C` above; `,` remove one cursor | -| Align selections | `&` align selection contents | -| Undo / redo | `u` / `U` | -| Delete / change / yank | `d` / `c` / `y` — acts on selection | -| Replace with yank | `R` replace selection with yanked text | -| Paste | `p` / `P`; registers `"` … | -| Register prefix | `"` selects a register for yank/paste/macro operations | -| Insert | `i` `a` `I` `A` `o` `O` | -| Repeat insert | `.` repeat the last insertion | -| Replace selected chars | `r` | -| Indent / format | `>` / `<`; `=` format (LSP) | -| Increment / decrement | `Ctrl-a` / `Ctrl-x` on selected numbers | -| Case | `~` toggle; lower/upper case via grave / `Alt-grave` (see Alt caveat above) | -| Join lines | `J`; `Alt-J` join keeping space (see Alt caveat above) | -| Toggle line comment | `Ctrl-c` | -| Macro record / replay | `Q` start/stop recording; `q` replay from the default `@` register | +| Action | Keys / notes | +| ---------------------- | ------------------------------------------------------------------------------------ | +| Extend selections | `v` select mode; motions extend instead of moving; `v` or `Esc` leaves mode | +| Line selection | `x` extend line; `X` line bounds; repeat or use a count for more lines | +| Collapse selections | `;` collapse selections back to cursors | +| Select all / regex | `%`; `s` regex in selections; `S` split on regex | +| Multiple cursors | `C` duplicate to next suitable line; `Alt-C` above; `,` keep only the primary cursor | +| Align selections | `&` align selection contents | +| Undo / redo | `u` / `U` | +| Delete / change / yank | `d` / `c` / `y` — acts on selection | +| Replace with yank | `R` replace selection with yanked text | +| Paste | `p` / `P`; registers `"` … | +| Register prefix | `"` selects a register for yank/paste/macro operations | +| Insert | `i` `a` `I` `A` `o` `O` | +| Repeat insert | `.` repeat the last insertion | +| Replace selected chars | `r` | +| Indent / format | `>` / `<`; `=` format (LSP) | +| Increment / decrement | `Ctrl-a` / `Ctrl-x` on selected numbers | +| Case | `~` toggle; lower/upper case via grave / `Alt-grave` (see Alt caveat above) | +| Join lines | `J`; `Alt-J` join keeping space (see Alt caveat above) | +| Toggle line comment | `Ctrl-c` | +| Macro record / replay | `Q` start/stop recording; `q` replay from the default `@` register | ### Search diff --git a/home/base/core/editors/neovim/README.md b/home/base/core/editors/neovim/README.md index 40c7b089..c3d9b8eb 100644 --- a/home/base/core/editors/neovim/README.md +++ b/home/base/core/editors/neovim/README.md @@ -62,9 +62,9 @@ Zellij shortcuts used often: | Left / down / up / right | `h` `j` `k` `l` (counts like `5j` work) | | Jump to matchpairs `()`, `{}`, `[]` | `%` | | Start / end of line | `0` / `$` | -| Sentence forward / backward | `(` / `)` | -| Paragraph forward / backward | `{` / `}` | -| Section forward / backward | `[[` / `]]` | +| Sentence forward / backward | `)` / `(` | +| Paragraph forward / backward | `}` / `{` | +| Section forward / backward | `]]` / `[[` | | Jump to marks | `'` + mark (Neovim may prompt) | Text objects: @@ -103,7 +103,7 @@ Misc: | Block visual | `` | | Fold close / open | `zc` / `zo` | | Go to definition | `gd` | -| Go to references | `gD` | +| Go to declaration | `gD` | | Comment line (if mapped) | e.g. `gcc` | | Action | Command | diff --git a/home/base/tui/editors/README.md b/home/base/tui/editors/README.md index 73fea76d..fe9e7125 100644 --- a/home/base/tui/editors/README.md +++ b/home/base/tui/editors/README.md @@ -1,7 +1,8 @@ # Editor tooling packages (heavy dependencies) -This directory intentionally holds **only** [`packages.nix`](./packages.nix): language servers, -formatters, compilers, and other editor-adjacent tools that pull in a large closure. +This directory intentionally keeps the heavy editor tooling in [`packages.nix`](./packages.nix): +language servers, formatters, compilers, and other editor-adjacent tools that pull in a large +closure. Editor programs, keymaps, `$EDITOR` defaults, and usage docs live under [`../../core/editors/`](../../core/editors/README.md) (Helix, Neovim backup, glossary, cheatsheets). diff --git a/home/linux/gui/README.md b/home/linux/gui/README.md index 7b61bf87..b66ede88 100644 --- a/home/linux/gui/README.md +++ b/home/linux/gui/README.md @@ -16,7 +16,8 @@ Manager. - **base**: Common desktop configurations shared across all environments, including: - **Noctalia**: native (v5) all-in-one Wayland desktop shell (replaces gammastep, swaylock, - anyrun, mako, waybar, wallpaper-switcher, wlogout, grim/slurp/satty, and other desktop tools) + anyrun, mako, waybar, wallpaper-switcher, grim/slurp/satty, and other desktop tools; `wlogout` + stays as an emergency session-menu fallback) - Creative tools and media applications - Development tools - Fcitx5 input method framework diff --git a/home/linux/gui/base/README.md b/home/linux/gui/base/README.md index 464050a2..0079ff7c 100644 --- a/home/linux/gui/base/README.md +++ b/home/linux/gui/base/README.md @@ -79,8 +79,8 @@ Noctalia consolidates functionality that previously required multiple tools: ### Applications -- **[`desktop-tools.nix`](./desktop-tools.nix)**: Wayland session tools (clipboard, color picker, - brightness, audio, screen recording, auto-mount, `wlogout` emergency fallback) +- **[`desktop-tools.nix`](./desktop-tools.nix)**: Wayland session tools (clipboard, brightness, + screen recording, auto-mount, virt-manager/virt-viewer, `wlogout` emergency fallback) - **[`browsers.nix`](./browsers.nix)**: Web browsers - **[`vscode.nix`](./vscode.nix)**: VS Code (GUI editor; the primary Zed config is shared from [`home/base/gui/zed-editor.nix`](../../../base/gui/zed-editor.nix)) diff --git a/home/linux/gui/i3/README.md b/home/linux/gui/i3/README.md index 218c0d09..4a377e78 100644 --- a/home/linux/gui/i3/README.md +++ b/home/linux/gui/i3/README.md @@ -58,8 +58,8 @@ The generated config is intentionally minimal: screen. That matches a real desktop and avoids a full-screen-sized viewport. - `exec --no-startup-id .../computer-use-init` — one-time session setup, see above. -There are no keybindings, bars or autostarted apps: agents drive the session through the drivers, -not the keyboard. +There are no keybindings or bars, and the only autostart is the one-time `computer-use-init` above: +agents drive the session through the drivers, not the keyboard. ## Manual access over VNC diff --git a/hosts/12kingdoms-youko/homelab-services/README.md b/hosts/12kingdoms-youko/homelab-services/README.md index 29fad387..2d3b6a9c 100644 --- a/hosts/12kingdoms-youko/homelab-services/README.md +++ b/hosts/12kingdoms-youko/homelab-services/README.md @@ -19,6 +19,10 @@ Services: 1. restic: Encrypted backups; hosts the REST server the desktops push to. 1. victoriametrics + vmalert + alertmanager + grafana: Monitor the metrics of my homelab. 1. homepage + uptime-kuma: Service dashboard and uptime checks. +1. immich: Photo and video library with ML search. +1. jellyfin: Media server. +1. rustfs: S3-compatible object storage (Loki chunks and Terraform state). +1. valkey: Redis-compatible cache for Immich. All the services assume a reverse proxy in front: they listen on localhost, and a caddy service listens on the local network interface and proxies requests to them. The exception is transmission, diff --git a/hosts/12kingdoms-youko/homelab-services/immich/README.md b/hosts/12kingdoms-youko/homelab-services/immich/README.md index b60b107c..2fd192ff 100644 --- a/hosts/12kingdoms-youko/homelab-services/immich/README.md +++ b/hosts/12kingdoms-youko/homelab-services/immich/README.md @@ -7,7 +7,7 @@ document is the agreed design and the rationale. - Browse and search the existing 36G phone gallery (`/data/fileshare/mydata/DCIM`) **in place**, with ML (faces, objects) and duplicate detection. -- Keep the footprint reasonable next to the k3s microVMs on the same 22G host. +- Keep the footprint reasonable next to the k3s microVMs on the same host. ## Non-goals (for now) @@ -91,8 +91,7 @@ document is the agreed design and the rationale. ## Resource budget -- Immich server + ML worker + Redis: roughly 2-4G RAM, alongside the k3s microVMs; youko has ~13G - available. +- Immich server + ML worker + Valkey: roughly 2-4G RAM, alongside the k3s microVMs. ## Rollout diff --git a/hosts/README.md b/hosts/README.md index fbda35e7..4376f8f6 100644 --- a/hosts/README.md +++ b/hosts/README.md @@ -44,7 +44,7 @@ Named after "Twelve Kingdoms": On 2026-09-29 the NVMe SSDs of `youko` and `shushou` were physically swapped, and the 2×4TB USB HDDs moved with the `youko` role to the other chassis. The reason was Jellyfin: HDR transcoding on the 5625U's Barceló iGPU could not keep up (~0.4–0.8×), while the 5900HX's Cezanne iGPU can (~1.68× for -1080p HDR). So the homelab-core role (all services + one k3s VM + the HDDs + the UPS) now runs on +1080p HDR). So the homelab-core role (all services + the k3s VMs + the HDDs + the UPS) now runs on the Beelink GTR5 and the k3s VM-host role on the UM560; the other services moving along is a side effect of swapping the role's disk, not a separate migration. Hostnames, IPs, and state followed the disks. @@ -82,9 +82,12 @@ networking wiring, secrets, and the eval tests a new host must pass, is in ## Deploying VM Hosts -The three VM hosts (`shoryu`, `shushou`, `youko`) attach their VMs (microVM taps and libvirt -domains) to the Linux bridge `br0`, with the physical NIC as a bridge port. The `k3s-test-1` cluster -runs as microVMs on top, using Cilium as its pod network (flannel disabled). +The three VM hosts (`shoryu`, `shushou`, `youko`) put their VMs on the Linux bridge `br0`, with the +physical NIC as a bridge port. NixOS guests run as microVMs (`microvm.nix`); the `k3s-test-1` +cluster is microVMs on top, using Cilium as its pod network (flannel disabled). Full-machine guests +run with qemu-kvm under libvirt instead: `shoryu` is the only host that enables `libvirtd` today +(the agent desktops `kana`/`ruby`). Non-NixOS guests (Ubuntu, Windows, Qubes OS) would take the same +qemu-kvm path; there are none right now. - `switch` is fine for changes that don't touch the network stack (e.g. journald or other service settings). Deploy serially (`-p 1`) and re-check VM reachability afterwards. diff --git a/hosts/idols-ai/README.md b/hosts/idols-ai/README.md index 62e824e6..a959d568 100644 --- a/hosts/idols-ai/README.md +++ b/hosts/idols-ai/README.md @@ -9,7 +9,7 @@ Related: - [disko-fs.nix](./disko-fs.nix) – main disk layout (ESP + LUKS + btrfs). From `nix-config/nixos-installer`: `nix run github:nix-community/disko -- --mode destroy,format,mount ../hosts/idols-ai/disko-fs.nix` -- [disko-fs-data.nix](./disko-fs-data.nix) – data disk layout (LUKS + btrfs at /persistent/data) +- [disko-fs-data.nix](./disko-fs-data.nix) – data disk layout (LUKS + btrfs at /data) ## TODOs diff --git a/hosts/idols-ai/disko-fs-data.nix b/hosts/idols-ai/disko-fs-data.nix index 48c51422..dabf97cf 100644 --- a/hosts/idols-ai/disko-fs-data.nix +++ b/hosts/idols-ai/disko-fs-data.nix @@ -1,4 +1,4 @@ -# Disko layout for idols-ai data disk (LUKS + btrfs, mount at /persistent/data). +# Disko layout for idols-ai data disk (LUKS + btrfs, mount at /data). # # Destroy, format & mount (wipes disk; from nixos-installer: cd nix-config/nixos-installer): # nix run github:nix-community/disko -- --mode destroy,format,mount ../hosts/idols-ai/disko-fs-data.nix diff --git a/hosts/k8s/README.md b/hosts/k8s/README.md index b7431a12..7722ed5e 100644 --- a/hosts/k8s/README.md +++ b/hosts/k8s/README.md @@ -53,9 +53,8 @@ guest service before proceeding to the next node. `node-role.kubernetes.io/control-plane:NoSchedule` 1. `k3s-test-1-worker-{1,2,3}` — workloads, running as microVMs -Placement: `worker-1` (4 vCPU / 16 GiB) runs on `shoryu`; `worker-2` (4 vCPU / 16 GiB) and -`worker-3` (2 vCPU / 8 GiB) run on `shushou`. `youko` has no worker because it has the least free -memory and also runs the homelab services. +Placement: `worker-1` (4 vCPU / 16 GiB) runs on `shoryu`; `worker-2` (4 vCPU / 16 GiB) runs on +`youko`; `worker-3` (2 vCPU / 8 GiB) runs on `shushou`. The master taint comes from kubelet's `registerWithTaints`, which only takes effect when the Node object is first created. These masters are long-lived and predate the config, so the taint was diff --git a/infra/README.md b/infra/README.md index 0e6ae0f7..c28a9e48 100644 --- a/infra/README.md +++ b/infra/README.md @@ -29,8 +29,8 @@ infra/ - **Loki Buckets**: Dedicated storage for Grafana Loki log aggregation - **Terraform Backend**: Centralized state management for all Terraform configurations -RustFS speaks the S3 API but not MinIO's Admin API, so buckets/lifecycle are managed with the AWS -provider and IAM users/policies with the official `rc` client. See +RustFS speaks the S3 API but not MinIO's Admin API, so buckets are managed with the AWS provider +while lifecycle rules and IAM users/policies use the official `rc` client. See [rustfs/README.md](./rustfs/README.md). ### External Resources @@ -52,7 +52,7 @@ Each subdirectory contains its own Terraform configuration: 2. **Deploy configuration**: ```bash - ./run.sh + bash run.sh ``` 3. **Manual deployment**: diff --git a/infra/rustfs/README.md b/infra/rustfs/README.md index 23b77e85..65a6854f 100644 --- a/infra/rustfs/README.md +++ b/infra/rustfs/README.md @@ -28,7 +28,7 @@ rc ilm rule add rustfs/k3s-test-1-loki-chunks --expiry-days 7 ``` If the buckets were carried over from MinIO (S3-level copy), they already exist; import them into -Terraform instead (`terraform import`, see the workspace READMEs). +Terraform instead (the `terraform import` commands are in each workspace's `run.sh`). ## IAM diff --git a/lib/README.md b/lib/README.md index 2d8017f9..b3bb92ec 100644 --- a/lib/README.md +++ b/lib/README.md @@ -17,14 +17,15 @@ reduce code duplication and make it easier to add new machines. ### Specialized Module Generators 5. **`genK3sServerModule.nix`** - K3s server node configuration generator -6. **`genVmHostModule.nix`** - physical VM host (bridge + libvirt) configuration generator -7. **`genMicrovmGuestModule.nix`** - NixOS microVM guest configuration generator -8. **`genLibvirtDomainXml.nix`** - libvirt domain XML generator (imported directly by host configs) +6. **`genK3sAgentModule.nix`** - K3s agent/worker node configuration generator +7. **`genVmHostModule.nix`** - physical VM host (bridge + libvirt) configuration generator +8. **`genMicrovmGuestModule.nix`** - NixOS microVM guest configuration generator +9. **`genLibvirtDomainXml.nix`** - libvirt domain XML generator (imported directly by host configs) ### Entry Point -9. **`default.nix`** - Main entry point that imports the generators and exports them as a single - attribute set, plus the `relativeToRoot` and `scanPaths` helpers +10. **`default.nix`** - Main entry point that imports the generators and exports them as a single + attribute set, plus the `relativeToRoot` and `scanPaths` helpers ## Usage diff --git a/modules/README.md b/modules/README.md index dd5d5ea0..f13dbd13 100644 --- a/modules/README.md +++ b/modules/README.md @@ -27,16 +27,17 @@ modules/ │ └── users.nix # macOS user management └── nixos/ # NixOS-specific modules ├── base/ # Base NixOS configuration + │ ├── btop.nix # System resource monitor │ ├── btrbk.nix # Local btrfs snapshots │ ├── core.nix # Core system settings │ ├── default.nix │ ├── i18n.nix # Internationalization │ ├── kernel-hardening.nix # Kernel hardening (module blacklisting) + │ ├── locate.nix # locate/updatedb file search │ ├── monitoring.nix # System monitoring │ ├── networking/ # Network configuration │ ├── nix.nix # Nix settings │ ├── packages.nix # System packages - │ ├── remote-building.nix # Remote build setup │ ├── restic-backup.nix # Encrypted off-host backups (see ../BACKUP.md) │ ├── ssh.nix # SSH daemon configuration │ ├── trash.nix # Trash retention cleanup @@ -44,6 +45,7 @@ modules/ │ └── zram.nix # ZRAM swap configuration ├── desktop.nix # Desktop environment configuration ├── desktop/ # Desktop-specific modules + │ ├── canokey.nix # CanoKey hardware token │ ├── computer-use.nix # Headless X11/i3 session for AI agents │ ├── default.nix │ ├── fhs.nix # FHS environment @@ -61,6 +63,7 @@ modules/ └── server/ # Server-specific modules ├── qemu-guest-hardware-configuration.nix ├── qemu-guest.nix # VM guest base module (libvirt/QEMU guests) + ├── remote-building.nix # Remote build setup ├── server-aarch64.nix ├── server-riscv64.nix └── server.nix diff --git a/nixos-installer/README.md b/nixos-installer/README.md index 4d74006a..70930e37 100644 --- a/nixos-installer/README.md +++ b/nixos-installer/README.md @@ -27,8 +27,9 @@ partitioning is no longer needed. ### 1. Partition and mount with disko (recommended) Layout is defined in [../hosts/idols-ai/disko-fs.nix](../hosts/idols-ai/disko-fs.nix): **nvme1n1**, -ESP (450M) + LUKS + btrfs (subvolumes: @nix, @guix, @persistent, @snapshots, @tmp, @swap). Root is -tmpfs; [preservation](https://github.com/nix-community/preservation) uses `/persistent`. +ESP (~600M) + LUKS + btrfs (subvolumes: `/` at `/btr_pool`, `@nix`, `@persistent`, `@snapshots`, +`@tmp`, `@swap`). Root is tmpfs; [preservation](https://github.com/nix-community/preservation) uses +`/persistent`. ```bash git clone https://github.com/ryan4yin/nix-config.git @@ -43,6 +44,9 @@ nix run github:nix-community/disko -- --mode destroy,format,mount ../hosts/idols # Mount only (e.g. after first format, without wiping): # nix run github:nix-community/disko -- --mode mount ../hosts/idols-ai/disko-fs.nix +# the separate data disk (mounts at /data): +nix run github:nix-community/disko -- --mode destroy,format,mount ../hosts/idols-ai/disko-fs-data.nix + # setup the automatic unlock via the tpm2 chip systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=0+7 /dev/ ``` diff --git a/nixos-installer/README.shoukei.md b/nixos-installer/README.shoukei.md index ae6cbeb0..fdeb4ce5 100755 --- a/nixos-installer/README.shoukei.md +++ b/nixos-installer/README.shoukei.md @@ -271,6 +271,9 @@ nixos-enter mv /etc/machine-id /persistent/etc/ mv /etc/ssh /persistent/etc/ +# leave the chroot; the remaining steps run from the live environment, where /mnt is the target +exit + # delete the generated configuration after editing rm -f /mnt/etc/nixos rm ~/nix-config/hosts/12kingdoms-shoukei/hardware-configuration-new.nix @@ -282,7 +285,7 @@ git config --global user.name "Ryan Yin" # git-1 git commit -am "feat: update hardware-configuration" # copy our configuration to the installed file system -cp -r ../nix-config /mnt/etc/nixos +cp -r ~/nix-config /mnt/etc/nixos # sync the disk, unmount the partitions, and close the encrypted device sync diff --git a/outputs/README.md b/outputs/README.md index d1c747ab..5cad6d74 100644 --- a/outputs/README.md +++ b/outputs/README.md @@ -114,7 +114,10 @@ All the outputs of this flake are defined here. │ ├── idols-ruby.nix │ ├── k3s-test-1-master-1.nix │ ├── k3s-test-1-master-2.nix - │ └── k3s-test-1-master-3.nix + │ ├── k3s-test-1-master-3.nix + │ ├── k3s-test-1-worker-1.nix + │ ├── k3s-test-1-worker-2.nix + │ └── k3s-test-1-worker-3.nix └── tests # eval tests (btrbk, computer-use-headless, hostname, # kernel, security-*, ups-metrics, ...) ``` diff --git a/secrets/README.md b/secrets/README.md index 0dd283d3..fa7afa02 100644 --- a/secrets/README.md +++ b/secrets/README.md @@ -84,23 +84,26 @@ Suppose you want to add a new secret file `xxx.age`. Follow these steps: # and users can decrypt the secrets by any of the corresponding private keys. let - # Get system's ssh public key by command: + # Get each desktop's ssh public key with: # cat /etc/ssh/ssh_host_ed25519_key.pub - # If you do not have this file, you can generate all the host keys by command: - # sudo ssh-keygen -A + # If the file does not exist, generate all host keys with: sudo ssh-keygen -A idol_ai = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINHZtzeaQyXwuRMLzoOAuTu8P9bu5yc5MBwo5LI3iWBV root@ai"; - # A key for recovery purpose, generated by `ssh-keygen -t ed25519 -a 256 -C "ryan@agenix-recovery"` with a strong passphrase - # and kept it offline in a safe place. + # An offline recovery key, generated with + # `ssh-keygen -t ed25519 -a 256 -C "ryan@agenix-recovery"` and kept in a safe place. recovery_key = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHnIGH+653Oe+GQaA8zjjj7HWMWp7bWXed4q5KqY4nqG ryan@agenix-recovery"; - systems = [ - idol_ai - fern + # Every secret stays decryptable by the desktops plus the recovery key. + desktop_keys = [ + idol_ai recovery_key ]; + + # The other hosts that need this specific secret. + hosts = [ ]; +in { - "./xxx.age".publicKeys = users ++ systems; + "./xxx.age".publicKeys = desktop_keys ++ hosts; } ``` @@ -183,6 +186,8 @@ Then, create `./secrets/nixos.nix` (or `./secrets/darwin.nix` on macOS) with the age.identityPaths = [ # using the host key for decryption # the host key is generated on every host locally by openssh, and will never leave the host. + # On a preservation host, use the /persistent path so the key exists at boot: + # "/persistent/etc/ssh/ssh_host_ed25519_key" "/etc/ssh/ssh_host_ed25519_key" ]; @@ -202,7 +207,7 @@ Then, create `./secrets/nixos.nix` (or `./secrets/darwin.nix` on macOS) with the From now on, every time you run `nixos-rebuild switch`, it will decrypt the secrets using the private keys defined in `age.identityPaths`. It will then symlink the secrets to the path defined by -the `age.secrets..path` argument, which defaults to `/etc/secrets`. +the `age.secrets..path` argument, which defaults to `/run/agenix/`. ## Adding a new host diff --git a/vars/README.md b/vars/README.md index 5813f9f3..1cd41088 100644 --- a/vars/README.md +++ b/vars/README.md @@ -28,7 +28,8 @@ Comprehensive network configuration including: - **Gateway settings**: Main router and proxy gateway configurations - **DNS servers**: IPv4 and IPv6 name servers -- **Host inventory**: Complete mapping of all hosts with their network interfaces and IP addresses +- **Host inventory**: static LAN hosts and their interfaces; DHCP/mobile hosts (such as the macOS + hosts) are omitted by design - **SSH configuration**: Remote builder aliases and known hosts configuration - **Network topology**: Physical machines, VMs, Kubernetes clusters, and SBCs @@ -36,7 +37,7 @@ Comprehensive network configuration including: The networking configuration covers: -- **Physical machines**: Desktop PCs, Apple Silicon systems, SBCs +- **Physical machines**: Desktop PCs, servers, and SBCs - **Virtual machines**: VM guests, K3s nodes - **Kubernetes clusters**: the `k3s-test-1` testing cluster - **Network infrastructure**: Routers, gateways, and DNS configuration