From 3a5b9ec4c659fbdb3ba47bf0a4c437304a3226f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?ryan4yin=20=7C=20=E4=BA=8C=E8=8A=B1?= Date: Sat, 3 Oct 2026 18:28:58 +0800 Subject: [PATCH] docs: README audit fixes and de-duplication (#371) --- README.md | 2 -- agents/README.md | 10 +++------ certs/README.md | 5 +++-- hardening/README.md | 9 +++----- home/README.md | 19 +++-------------- home/base/core/editors/helix/README.md | 16 +++++++------- home/base/core/editors/neovim/README.md | 14 +++---------- home/base/tui/agents/README.md | 4 ++-- home/base/tui/encryption/README.md | 4 ++-- home/base/tui/gpg/README.md | 2 +- home/linux/README.md | 2 +- home/linux/gui/README.md | 5 ++--- home/linux/gui/base/README.md | 3 ++- home/linux/gui/base/fcitx5/README.md | 4 ++++ .../grafana/dashboards/README.md | 5 ++++- .../homelab-services/immich/README.md | 4 ++-- .../homelab-services/monitoring/README.md | 4 ++-- .../homelab-services/monitoring/alert.nix | 4 ++-- .../monitoring/alert_rules/README.md | 5 +++++ .../README.md | 5 +++++ .../k8s.yml | 0 .../node-exporter.yml | 0 hosts/README.md | 17 +++++++-------- hosts/idols-ai/README.md | 2 +- hosts/idols-akane/README.md | 2 +- hosts/idols-kana/README.md | 6 +++++- hosts/idols-ruby/README.md | 7 ++++++- hosts/k8s/disko-config/README.md | 8 ++++--- infra/rustfs/README.md | 6 ++++++ lib/README.md | 21 +++++++++---------- modules/README.md | 9 +------- .../desktop/networking/sunshine/README.md | 2 +- nixos-installer/README.md | 18 +++++++++------- outputs/README.md | 12 ++++++----- secrets/README.md | 16 ++++++++------ vars/README.md | 8 ++----- 36 files changed, 131 insertions(+), 129 deletions(-) rename hosts/12kingdoms-youko/homelab-services/monitoring/{recoding_rules => recording_rules}/README.md (62%) rename hosts/12kingdoms-youko/homelab-services/monitoring/{recoding_rules => recording_rules}/k8s.yml (100%) rename hosts/12kingdoms-youko/homelab-services/monitoring/{recoding_rules => recording_rules}/node-exporter.yml (100%) diff --git a/README.md b/README.md index 9d48a62d..89ee16a6 100644 --- a/README.md +++ b/README.md @@ -116,8 +116,6 @@ hardening, and [./WORKAROUNDS.md](./WORKAROUNDS.md) for temporary exceptions and > [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. - Updating flake inputs and rolling the result out safely is a procedure, not a single command. Follow [`.agents/skills/nix-config-update/SKILL.md`](./.agents/skills/nix-config-update/SKILL.md). diff --git a/agents/README.md b/agents/README.md index d8348776..e537328a 100644 --- a/agents/README.md +++ b/agents/README.md @@ -37,13 +37,9 @@ the Home Manager module [`home/base/tui/agents/`](../home/base/tui/agents/README ## Deployment [`home/base/tui/agents/rules.nix`](../home/base/tui/agents/rules.nix) links `AGENTS.md` into every -supported agent config directory as an out-of-store symlink, so edits apply without a rebuild: - -- Codex: `AGENTS.md` -> `${CODEX_HOME:-~/.codex}/AGENTS.md` -- OpenCode: `AGENTS.md` -> `${XDG_CONFIG_HOME:-~/.config}/opencode/AGENTS.md` -- Pi: `AGENTS.md` -> `~/.pi/agent/AGENTS.md` -- OMP: `AGENTS.md` -> `~/.omp/agent/AGENTS.md` -- Generic cross-tool (read by Kimi Code): `AGENTS.md` -> `~/.agents/AGENTS.md` +supported agent config directory as an out-of-store symlink, so edits apply without a rebuild. The +per-agent target list lives in that module's +[README](../home/base/tui/agents/README.md#deployed-rule-targets). The module is imported through `home/base/tui`, so it covers the hosts that import `home/linux/gui.nix` or the macOS `home/darwin` stack; core-only servers are unchanged. diff --git a/certs/README.md b/certs/README.md index 4bc66047..aa6ad3aa 100644 --- a/certs/README.md +++ b/certs/README.md @@ -13,8 +13,9 @@ use. It is used to issue certificates for my own servers and services. ## Security Notes -All private keys (`.key` files) are ignored by git and stored in a private secrets repository. The -public certificates and configuration files are committed to this repository for reference. +Private keys (`.key`) and certificate signing requests (`.csr`) are ignored by git; the keys are +stored in a private secrets repository. The public certificates and configuration files are +committed to this repository for reference. ## Usage diff --git a/hardening/README.md b/hardening/README.md index aa34da74..cee860ea 100644 --- a/hardening/README.md +++ b/hardening/README.md @@ -94,10 +94,9 @@ hardening/ ## NOTE -**Running untrusted code is never safe, kernel hardening & sandboxing cannot change this**. - -If you want to run untrusted code, please use a VM & an isolated network environment, which will -provide a much higher level of security. +**Running untrusted code is never safe, kernel hardening & sandboxing cannot change this**; run +untrusted code in a VM on an isolated network. The threat model lives in +[`SECURITY.md`](../SECURITY.md). ## References @@ -110,5 +109,3 @@ provide a much higher level of security. - apparmor configs: - https://github.com/zramctl/dotfiles/blob/4fe177f6984154960942bb47d5a375098ec6ed6a/modules/nixos/security/apparmor.nix#L4 - https://git.grimmauld.de/Grimmauld/grimm-nixos-laptop/src/branch/main/hardening -- Others: - - Directly via `buildFHSUserEnvBubblewrap`: diff --git a/home/README.md b/home/README.md index 76a7572b..32f73ae3 100644 --- a/home/README.md +++ b/home/README.md @@ -6,20 +6,7 @@ This directory contains all Home Manager configurations organized by platform an ``` home/ -├── base/ # Cross-platform home manager configurations -│ ├── core/ # Essential applications and settings -│ │ ├── editors/ # Editor configurations (Neovim, Helix) -│ │ ├── shells/ # Shell configurations (bash, Nushell) -│ │ └── ... -│ ├── gui/ # GUI applications and desktop settings -│ │ ├── terminal/ # Terminal emulators (Ghostty, Kitty, etc.) -│ │ └── ... -│ ├── tui/ # Terminal/TUI applications -│ │ ├── agents/ # AI coding agents (rules deployment, CLIs, env) -│ │ ├── editors/ # Heavy editor/tooling pkgs only (`packages.nix`; core editors live under `core/editors`) -│ │ ├── encryption/ # Encryption and security tooling -│ │ └── ... -│ └── home.nix # Main home manager entry point +├── base/ # Cross-platform home manager configurations (see base/README.md) ├── linux/ # Linux-specific home manager configurations │ ├── base/ # Linux base configurations │ ├── gui/ # Linux GUI applications @@ -28,7 +15,7 @@ home/ │ │ └── ... │ └── ... ├── hosts/ # Host-specific home manager entry modules -│ ├── linux/ # Linux host home modules (ai, shoukei, kana, ruby, k3s-*, etc.) +│ ├── linux/ # Linux host home modules (idols-ai, 12kingdoms-shoukei, idols-kana, idols-ruby, k3s-test-1-worker-*, etc.) │ └── darwin/ # macOS host home modules (fern, frieren) └── darwin/ # macOS-specific home manager configurations ├── proxy/ # Proxy configurations @@ -43,7 +30,7 @@ home/ 2. **linux**: Linux-specific configuration - Desktop environments (Noctalia Shell, Niri compositor) - - Headless computer-use session (`gui/i3`, Xvfb + i3; see `gui/i3/README.md`) + - Headless computer-use session (see `gui/i3/README.md`) - Linux-specific GUI applications - System integration tools diff --git a/home/base/core/editors/helix/README.md b/home/base/core/editors/helix/README.md index bd4c0320..b9a2d4ef 100644 --- a/home/base/core/editors/helix/README.md +++ b/home/base/core/editors/helix/README.md @@ -109,19 +109,19 @@ normal-mode remaps: **`Ctrl+Shift+o`** → jump backward (leaving `Ctrl+o` free | 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) | +| Case | `~` toggle; lower/upper case via grave / `Alt-grave` | +| Join lines | `J`; `Alt-J` join keeping space | | Toggle line comment | `Ctrl-c` | | Macro record / replay | `Q` start/stop recording; `q` replay from the default `@` register | ### Search -| Action | Keys | -| -------------------- | --------------------------------------------------------------- | -| Search / reverse | `/` / `?` | -| Next / prev match | `n` / `N` | -| Selection as pattern | `*` (word bounds); `Alt-*` raw selection (see Alt caveat above) | -| Split on newlines | `Alt-s` | +| Action | Keys | +| -------------------- | ---------------------------------------- | +| Search / reverse | `/` / `?` | +| Next / prev match | `n` / `N` | +| Selection as pattern | `*` (word bounds); `Alt-*` raw selection | +| Split on newlines | `Alt-s` | Use **extend mode** (`v`) with `n` / `N` to add matches to multi-cursors ([keymap](https://docs.helix-editor.com/keymap.html#select--extend-mode)). diff --git a/home/base/core/editors/neovim/README.md b/home/base/core/editors/neovim/README.md index 38f0208f..43f43339 100644 --- a/home/base/core/editors/neovim/README.md +++ b/home/base/core/editors/neovim/README.md @@ -27,17 +27,9 @@ Neovim and vim share the motions below. ### Terminal related -tuios shortcuts used often (leader is `Ctrl + B`): - -| Action | tuios shortcut | -| ------------------- | -------------------------- | -| New pane | `n` (window mode) | -| Floating terminal | `Ctrl + B`, then `Alt + F` | -| Split horizontal | `Ctrl + B`, then `-` | -| Split vertical | `Ctrl + B`, then `\` | -| Command palette | `Ctrl + P` | -| Detach | `Ctrl + B`, then `d` | -| Run a shell command | `!xxx` | +For the common **tuios** pane shortcuts, see the table in +[`../helix/README.md`](../helix/README.md#terminal-related). To run a shell command from Vim, use +`:!`. ### File management diff --git a/home/base/tui/agents/README.md b/home/base/tui/agents/README.md index 5a8fcd56..40db63bc 100644 --- a/home/base/tui/agents/README.md +++ b/home/base/tui/agents/README.md @@ -10,8 +10,8 @@ Nix dependency; this module only wires it into place. ## Files - `rules.nix`: links the global rules to every agent's config location. -- `packages.nix`: agent CLIs (`codex`, `opencode2`, `kimi-code`, `pi`, `omp`) and the Grafana MCP - server, from the `llm-agents` flake input. +- `packages.nix`: agent CLIs (`codex`, `opencode2`, `kimi-code`, `pi`, `omp`) from the `llm-agents` + flake input, plus `pkgs.mcp-grafana` for the Grafana MCP server. - `env.nix`: telemetry and auto-update opt-outs for the agents. ## Deployed rule targets diff --git a/home/base/tui/encryption/README.md b/home/base/tui/encryption/README.md index b7ff74b9..92cf2f8a 100644 --- a/home/base/tui/encryption/README.md +++ b/home/base/tui/encryption/README.md @@ -22,8 +22,8 @@ recommended, as it use KMS for key management. ## Symmetric Encryption -Both age & GnuPG provide symmetric encryption, which is useful for encrypting files for a specific -user. +Both age & GnuPG provide symmetric encryption, where a passphrase encrypts and decrypts the file +instead of a recipient key. As described in [age Format v1][age Format v1], age use scrypt to encrypt and decrypt the file key with a provided passphrase, which is more secure than GnuPG's symmetric encryption. diff --git a/home/base/tui/gpg/README.md b/home/base/tui/gpg/README.md index bccc451e..d7605d07 100644 --- a/home/base/tui/gpg/README.md +++ b/home/base/tui/gpg/README.md @@ -498,7 +498,7 @@ gpg --delete-secret-keys ryan4yin@linux.com rm ~/.gnupg/openpgp-revocs.d/C8D84EBC5F82494F432ACEF042E49B284C30A0DA.rev # import our subkeys back -age --decrypt -o ryan4yin-primary-key.priv ryan4yin-primary-key.priv.age +age --decrypt -o ryan4yin-gpg-subkeys.priv ryan4yin-gpg-subkeys.priv.age gpg --import ryan4yin-gpg-subkeys.priv ``` diff --git a/home/linux/README.md b/home/linux/README.md index 7af6608c..63ea0205 100644 --- a/home/linux/README.md +++ b/home/linux/README.md @@ -16,7 +16,7 @@ cases. - **gui/**: Desktop environment configurations - **niri/**: Niri compositor configuration - - **i3/**: Headless X11 computer-use session (Xvfb + i3) + - **i3/**: Headless computer-use session (see `gui/i3/README.md`) - **base/**: Common desktop applications and services ### Available Entry Points diff --git a/home/linux/gui/README.md b/home/linux/gui/README.md index b66ede88..d871b6c5 100644 --- a/home/linux/gui/README.md +++ b/home/linux/gui/README.md @@ -15,9 +15,8 @@ Manager. ### Base Desktop Environment - **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, grim/slurp/satty, and other desktop tools; `wlogout` - stays as an emergency session-menu fallback) + - **Noctalia**: native (v5) all-in-one Wayland desktop shell; see + [`base/README.md`](./base/README.md) for the components it replaces - 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 d7ab40a9..3a5fe69a 100644 --- a/home/linux/gui/base/README.md +++ b/home/linux/gui/base/README.md @@ -75,7 +75,8 @@ Noctalia consolidates functionality that previously required multiple tools: ### Input & Localization -- **[`fcitx5/`](./fcitx5/)**: Fcitx5 input method with Mozc (Japanese input) +- **[`fcitx5/`](./fcitx5/)**: Fcitx5 input method with Rime (Chinese), Mozc (Japanese), and Hangul + (Korean) engines ### Applications diff --git a/home/linux/gui/base/fcitx5/README.md b/home/linux/gui/base/fcitx5/README.md index 0b50b9f5..508f31cd 100644 --- a/home/linux/gui/base/fcitx5/README.md +++ b/home/linux/gui/base/fcitx5/README.md @@ -1,5 +1,9 @@ # fcitx5 - IME +fcitx5 is enabled in `default.nix` with the [flypy](https://flypy.com/) Rime schema (Chinese), +`fcitx5-mozc-ut` (Japanese), and `fcitx5-hangul` (Korean), alongside the US keyboard layouts. The +Rime data ships in the [`overlays/fcitx5`](../../../../../overlays/fcitx5/) overlay. + ## Available Configurations - `profile` → Symlink will be created at: `~/.config/fcitx5/profile` diff --git a/hosts/12kingdoms-youko/homelab-services/grafana/dashboards/README.md b/hosts/12kingdoms-youko/homelab-services/grafana/dashboards/README.md index 1f71040f..842f3864 100644 --- a/hosts/12kingdoms-youko/homelab-services/grafana/dashboards/README.md +++ b/hosts/12kingdoms-youko/homelab-services/grafana/dashboards/README.md @@ -6,6 +6,8 @@ 2. https://grafana.com/grafana/dashboards/9578-alertmanager/ 3. `smartctl.json` — drive/SSD SMART health (wear, spare, media errors, temperature). Custom, built on the `smartctl_exporter` metrics. +4. `gpu.json` — GPU utilization, VRAM, and temperature. +5. `nut-exporter.json` — UPS status (battery, load, runtime) from the NUT exporter. ## Kubernetes @@ -25,7 +27,8 @@ mixin provides a comprehensive package for monitoring Loki in production. ## Databases 1. PostgreSQL: https://grafana.com/grafana/dashboards/9628-postgresql-database/ - - Requires Prometheus PostgreSQL exporter metrics. See: wrouesnel/postgres_exporter + - Requires Prometheus PostgreSQL exporter metrics. See: + 1. CloudNative-PG: - Instance: https://github.com/cloudnative-pg/grafana-dashboards/blob/main/charts/cluster/grafana-dashboard.json diff --git a/hosts/12kingdoms-youko/homelab-services/immich/README.md b/hosts/12kingdoms-youko/homelab-services/immich/README.md index 2fd192ff..f18d8cbb 100644 --- a/hosts/12kingdoms-youko/homelab-services/immich/README.md +++ b/hosts/12kingdoms-youko/homelab-services/immich/README.md @@ -13,7 +13,7 @@ document is the agreed design and the rationale. - Scheduled phone background backup (the mobile app is used for manual uploads). - Multi-user / family accounts and public share links. -- Off-host/off-site copy — deferred to the planned cloud backup (see Backup). +- Off-host/off-site copy (see Backup). ## Decisions @@ -34,7 +34,7 @@ document is the agreed design and the rationale. - `services.immich.database.enable = true` and `createDB = true`: the module adds `pgvector` + `vectorchord` to `services.postgresql`, sets `shared_preload_libraries = [ "vchord.so" ]`, and creates the `immich` database/user. Confirmed present in this flake's nixpkgs: PG 16.15, - `pgvector` 0.8.6, `vectorchord` 1.1.1, `immich` 3.2.2. + `pgvector` 0.8.6, `vectorchord` 1.1.1, `immich` 3.2.4. - `services.immich.redis.enable = false` with `host = "127.0.0.1"` and `port = 6379`: Immich uses the shared Valkey instance (`../valkey.nix`) over loopback TCP; the module then passes `REDIS_HOSTNAME`/`REDIS_PORT`. diff --git a/hosts/12kingdoms-youko/homelab-services/monitoring/README.md b/hosts/12kingdoms-youko/homelab-services/monitoring/README.md index d40bfe85..b2810b61 100644 --- a/hosts/12kingdoms-youko/homelab-services/monitoring/README.md +++ b/hosts/12kingdoms-youko/homelab-services/monitoring/README.md @@ -1,11 +1,11 @@ # Monitoring & Alerting -## Alert Rules & Recoding Rules +## Alert Rules & Recording Rules - [awesome-prometheus-alerts](https://github.com/samber/awesome-prometheus-alerts) - Collection of Prometheus alerting rules. - [victoria-metrics-k8s-stack/files/rules](https://github.com/VictoriaMetrics/helm-charts/tree/master/charts/victoria-metrics-k8s-stack/files/rules/generated) - - Alert Rules & Recoding Rules used by kube-prometheus-stack. + - Alert Rules & Recording Rules used by kube-prometheus-stack. ## TODO diff --git a/hosts/12kingdoms-youko/homelab-services/monitoring/alert.nix b/hosts/12kingdoms-youko/homelab-services/monitoring/alert.nix index ef5deee5..f39bbf49 100644 --- a/hosts/12kingdoms-youko/homelab-services/monitoring/alert.nix +++ b/hosts/12kingdoms-youko/homelab-services/monitoring/alert.nix @@ -21,8 +21,8 @@ rule = [ "${./alert_rules}/*.yml" "${./alert_rules}/*.yaml" - "${./recoding_rules}/*.yml" - "${./recoding_rules}/*.yaml" + "${./recording_rules}/*.yml" + "${./recording_rules}/*.yaml" ]; # https://docs.victoriametrics.com/victoriametrics/vmalert/#link-to-alert-source # Set this two args to generate the correct `.GeneratorURL` diff --git a/hosts/12kingdoms-youko/homelab-services/monitoring/alert_rules/README.md b/hosts/12kingdoms-youko/homelab-services/monitoring/alert_rules/README.md index 40e55cb1..63a6c0b6 100644 --- a/hosts/12kingdoms-youko/homelab-services/monitoring/alert_rules/README.md +++ b/hosts/12kingdoms-youko/homelab-services/monitoring/alert_rules/README.md @@ -6,3 +6,8 @@ met for a specific resource within its scope, the system generates a triggered a actual instance of the condition being met. These rules specify the data to monitor, the trigger threshold, and the resulting actions, like sending notifications to specific receivers or performing automated tasks. + +## How these files are loaded + +[`../alert.nix`](../alert.nix) passes every `*.yml` and `*.yaml` in this directory to `vmalert` as a +rule file; other extensions are ignored. One rule group per file is easiest to review. diff --git a/hosts/12kingdoms-youko/homelab-services/monitoring/recoding_rules/README.md b/hosts/12kingdoms-youko/homelab-services/monitoring/recording_rules/README.md similarity index 62% rename from hosts/12kingdoms-youko/homelab-services/monitoring/recoding_rules/README.md rename to hosts/12kingdoms-youko/homelab-services/monitoring/recording_rules/README.md index 9af3baf9..f07dc320 100644 --- a/hosts/12kingdoms-youko/homelab-services/monitoring/recoding_rules/README.md +++ b/hosts/12kingdoms-youko/homelab-services/monitoring/recording_rules/README.md @@ -5,3 +5,8 @@ evaluated periodically to create new, pre-computed time series metrics. These rules store the results in a metric backend, significantly speeding up queries for dashboards and other alerts, and reducing system load by avoiding the re-computation of data. + +## How these files are loaded + +[`../alert.nix`](../alert.nix) passes every `*.yml` and `*.yaml` in this directory to `vmalert` as a +rule file; other extensions are ignored. One rule group per file is easiest to review. diff --git a/hosts/12kingdoms-youko/homelab-services/monitoring/recoding_rules/k8s.yml b/hosts/12kingdoms-youko/homelab-services/monitoring/recording_rules/k8s.yml similarity index 100% rename from hosts/12kingdoms-youko/homelab-services/monitoring/recoding_rules/k8s.yml rename to hosts/12kingdoms-youko/homelab-services/monitoring/recording_rules/k8s.yml diff --git a/hosts/12kingdoms-youko/homelab-services/monitoring/recoding_rules/node-exporter.yml b/hosts/12kingdoms-youko/homelab-services/monitoring/recording_rules/node-exporter.yml similarity index 100% rename from hosts/12kingdoms-youko/homelab-services/monitoring/recoding_rules/node-exporter.yml rename to hosts/12kingdoms-youko/homelab-services/monitoring/recording_rules/node-exporter.yml diff --git a/hosts/README.md b/hosts/README.md index 1e5baf28..22af586a 100644 --- a/hosts/README.md +++ b/hosts/README.md @@ -54,9 +54,8 @@ disks. #### `k8s` - Kubernetes Infrastructure - **VM Cluster**: 3 physical mini PCs (shoryu, shushou, youko) running all VMs -- **K3s Testing**: `k3s-test-1-master-{1,2,3}` (control plane; one per host) + - `k3s-test-1-worker-{1,2,3}` (workloads; `worker-1` on `shoryu`, `worker-2` on `youko`, `worker-3` - on `shushou`), running as microVMs +- **K3s Testing**: `k3s-test-1` control plane and workers, running as microVMs; placement and + rollout are documented in [`k8s/README.md`](./k8s/README.md) ### External Systems @@ -65,7 +64,7 @@ disks. All my riscv64 hosts: -![](/_img/2023-08-16_nixos-riscv-cluster.webp) +![](../_img/2023-08-16_nixos-riscv-cluster.webp) ## Naming Conventions @@ -118,22 +117,22 @@ various changes under the hood, so I need to build much more packages than usual the reasons why the cluster was originally built, and another reason is distributed building is cool! -![](/_img/2023-06-17_nix-distributed-building.webp) +![](../_img/2023-06-17_nix-distributed-building.webp) -![](/_img/2023-06-17_nix-distributed-building-log.webp) +![](../_img/2023-06-17_nix-distributed-building-log.webp) ## References [Oshi no Ko 【推しの子】 - Wikipedia](https://en.wikipedia.org/wiki/Oshi_no_Ko): -![](/_img/idols-famaily.webp) ![](/_img/idols-ai.webp) +![](../_img/idols-famaily.webp) ![](../_img/idols-ai.webp) [The Rolling Girls【ローリング☆ガールズ】 - Wikipedia](https://en.wikipedia.org/wiki/The_Rolling_Girls): -![](/_img/rolling_girls.webp) +![](../_img/rolling_girls.webp) [List of Twelve Kingdoms characters](https://en.wikipedia.org/wiki/List_of_Twelve_Kingdoms_characters) -![](/_img/12kingdoms-1.webp) ![](/_img/12kingdoms-Youko-Rakushun.webp) +![](../_img/12kingdoms-1.webp) ![](../_img/12kingdoms-Youko-Rakushun.webp) [List of Frieren characters](https://en.wikipedia.org/wiki/List_of_Frieren_characters) diff --git a/hosts/idols-ai/README.md b/hosts/idols-ai/README.md index dadfcaaa..5a806ac5 100644 --- a/hosts/idols-ai/README.md +++ b/hosts/idols-ai/README.md @@ -1,7 +1,7 @@ # Host - AI Desktop (NixOS + preservation, LUKS + btrfs on nvme). Disk layout is declarative via -[disko](./disko-fs.nix) (target device: **nvme1n1**). +[disko](./disko-fs.nix) (target device: the KINGBANK NVMe by `/dev/disk/by-id/`, set in that file). Related: diff --git a/hosts/idols-akane/README.md b/hosts/idols-akane/README.md index 59446487..243bfedc 100644 --- a/hosts/idols-akane/README.md +++ b/hosts/idols-akane/README.md @@ -14,7 +14,7 @@ nixos-install --root /mnt --flake .#akane --no-root-password --show-trace --verb # enter into the installed system, check password & users # `su ryan` => `sudo -i` => enter ryan's password => successfully login -# if login failed, check the password you set in install-1, and try again +# if login failed, check the initial password you set in vars/default.nix, and try again nixos-enter reboot diff --git a/hosts/idols-kana/README.md b/hosts/idols-kana/README.md index 1c09a4f7..cb16ecc8 100644 --- a/hosts/idols-kana/README.md +++ b/hosts/idols-kana/README.md @@ -1,3 +1,7 @@ # Idols - Kana -Run AI Agents +NixOS VM running under libvirt on `shoryu`, used to run AI agents. It imports the agent and +computer-use modules from [`idols-ruby`](../idols-ruby/). + +- Deploy from the VM with `just local`. +- Host inventory and role context: [`../README.md`](../README.md). diff --git a/hosts/idols-ruby/README.md b/hosts/idols-ruby/README.md index 4a91ca4d..89449ccd 100644 --- a/hosts/idols-ruby/README.md +++ b/hosts/idols-ruby/README.md @@ -1,3 +1,8 @@ # Idols - Ruby -Run AI Agents +NixOS VM running under libvirt on `shoryu`, used to run AI agents. It owns the shared agent and +computer-use modules (`packages.nix`, `computer-use.nix`, `oci-containers/`) that +[`idols-kana`](../idols-kana/) imports, and is the only host with a `*-nixos-tests` output. + +- Deploy from the VM with `just local`. +- Host inventory and role context: [`../README.md`](../README.md). diff --git a/hosts/k8s/disko-config/README.md b/hosts/k8s/disko-config/README.md index b7649719..9a978e4d 100644 --- a/hosts/k8s/disko-config/README.md +++ b/hosts/k8s/disko-config/README.md @@ -3,14 +3,16 @@ ## Partition the SSD & install NixOS via disko ```bash -# enter an shell with git/vim/ssh-agent/gnumake available -nix-shell -p git vim gnumake +# enter a shell with git/vim/ssh/gnumake available +nix-shell -p git vim gnumake openssh # clone this repository git clone https://github.com/ryan4yin/nix-config.git cd nix-config ## 1. partition & format the disk via disko +# WARNING: `destroy,format,mount` wipes the target disk. host-disko-fs.nix +# defaults to /dev/nvme0n1; review and edit that device first if the target differs. # encrypt the root partition with luks2 and argon2id, will prompt for a passphrase, which will be used to unlock the partition. sudo nix --experimental-features "nix-command flakes" run github:nix-community/disko -- --mode destroy,format,mount hosts/k8s/disko-config/host-disko-fs.nix ## 2. setup the automatic unlock via the tpm2 chip @@ -21,7 +23,7 @@ sudo nixos-install --root /mnt --no-root-password --show-trace --verbose --flake # enter into the installed system, check password & users # `su ryan` => `sudo -i` => enter ryan's password => successfully login -# if login failed, check the password you set in install-1, and try again +# if login failed, check the initial password you set in vars/default.nix, and try again nixos-enter # NOTE: DO NOT skip this step!!! diff --git a/infra/rustfs/README.md b/infra/rustfs/README.md index 65a6854f..28cd72b2 100644 --- a/infra/rustfs/README.md +++ b/infra/rustfs/README.md @@ -4,6 +4,12 @@ RustFS replaced the retired MinIO at `s3.writefor.fun` (console: `s3-console.wri service is declared in nix-config on the youko host; this directory manages its buckets/lifecycle and documents the IAM setup. +## Installing `rc` + +`rc` is RustFS's S3-compatible CLI ([rustfs/cli](https://github.com/rustfs/cli)); it is not in +nixpkgs. Download the Linux release archive from and put +the `rc` binary on `PATH`. + ## Credentials RustFS has no separate "root user" name: the root **access key** acts as the user and the **secret diff --git a/lib/README.md b/lib/README.md index 9482f70b..7d7df236 100644 --- a/lib/README.md +++ b/lib/README.md @@ -7,25 +7,24 @@ reduce code duplication and make it easier to add new machines. ### Core System Generators -1. **`attrs.nix`** - Attribute set manipulation utilities -2. **`macosSystem.nix`** - macOS configuration generator for +1. **`macosSystem.nix`** - macOS configuration generator for [nix-darwin](https://github.com/LnL7/nix-darwin) -3. **`nixosSystem.nix`** - NixOS configuration generator -4. **`colmenaSystem.nix`** - Remote deployment configuration for +2. **`nixosSystem.nix`** - NixOS configuration generator +3. **`colmenaSystem.nix`** - Remote deployment configuration for [colmena](https://github.com/nix-community/colmena) ### Specialized Module Generators -5. **`genK3sServerModule.nix`** - K3s server node configuration generator -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) +4. **`genK3sServerModule.nix`** - K3s server node configuration generator +5. **`genK3sAgentModule.nix`** - K3s agent/worker 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) ### Entry Point -10. **`default.nix`** - Main entry point that imports the generators and exports them as a single - attribute set, plus the `relativeToRoot` and `scanPaths` helpers +9. **`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 990414e2..ea008e9e 100644 --- a/modules/README.md +++ b/modules/README.md @@ -64,7 +64,7 @@ modules/ ├── qemu-guest.nix # VM guest base module (libvirt/QEMU guests) ├── remote-building.nix # Remote build setup ├── server-aarch64.nix - ├── server-riscv64.nix + ├── server-riscv64.nix # module only; the riscv64 output is disabled └── server.nix ``` @@ -107,10 +107,3 @@ Modules are imported based on platform detection: - **NixOS Systems**: Import `nixos/` modules - **macOS Systems**: Import `darwin/` modules - **All Systems**: Import `base/` modules for shared configuration - -## Architecture Support - -- **x86_64-linux**: Desktop and server configurations -- **aarch64-linux**: ARM64 Linux systems -- **aarch64-darwin**: Apple Silicon macOS systems -- **server-riscv64**: RISC-V server configurations diff --git a/modules/nixos/desktop/networking/sunshine/README.md b/modules/nixos/desktop/networking/sunshine/README.md index da04e593..8764a0e9 100644 --- a/modules/nixos/desktop/networking/sunshine/README.md +++ b/modules/nixos/desktop/networking/sunshine/README.md @@ -21,7 +21,7 @@ minor GPU and memory overhead. Options: ```text --u USER session user (defaults to SUDO_USER) +-u USER session user (defaults to $SUDO_USER, else ryan) -t TTY tty device, for example /dev/tty2 -c COMMAND Wayland session command (defaults to niri --session) -f, --force replace an existing Niri session without confirmation diff --git a/nixos-installer/README.md b/nixos-installer/README.md index 70930e37..941fce5d 100644 --- a/nixos-installer/README.md +++ b/nixos-installer/README.md @@ -23,13 +23,17 @@ partitioning is no longer needed. ## Steps to deploy 1. Create a USB install medium from the official NixOS ISO and boot from it. +2. Review + [`../hosts/idols-ai/hardware-configuration.nix`](../hosts/idols-ai/hardware-configuration.nix) + against the target machine before installing; after the disk is mounted, regenerate it with + `nixos-generate-config --root /mnt` if the hardware differs. ### 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 (~600M) + LUKS + btrfs (subvolumes: `/` at `/btr_pool`, `@nix`, `@persistent`, `@snapshots`, -`@tmp`, `@swap`). Root is tmpfs; [preservation](https://github.com/nix-community/preservation) uses -`/persistent`. +Layout is defined in [../hosts/idols-ai/disko-fs.nix](../hosts/idols-ai/disko-fs.nix): the KINGBANK +NVMe selected by `/dev/disk/by-id/`, 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 @@ -38,7 +42,7 @@ cd nix-config/nixos-installer sudo su # encrypt the root partition with luks2 and argon2id, will prompt for a passphrase, which will be used to unlock the partition. -# WARNING: destroys all data on nvme1n1. Layout is mounted at /mnt by default. +# WARNING: destroys all data on the target disk. Layout is mounted at /mnt by default. nix run github:nix-community/disko -- --mode destroy,format,mount ../hosts/idols-ai/disko-fs.nix # Mount only (e.g. after first format, without wiping): @@ -83,8 +87,8 @@ umount -R /mnt reboot ``` -After reboot, set the boot order in firmware so the system boots from nvme1n1. The old disk (e.g. -nvme0n1) can be reused for something else. +After reboot, set the boot order in firmware so the system boots from the newly installed NixOS +disk. The old disk can be reused for something else. ### Optional: use a cache mirror diff --git a/outputs/README.md b/outputs/README.md index 83bec668..ebeac8c8 100644 --- a/outputs/README.md +++ b/outputs/README.md @@ -46,10 +46,10 @@ suite passes when every `expr` equals its `expected`. Some tests iterate over every configuration, so a new host is covered automatically and must satisfy them. Others name specific hosts and only cover a new host if you add it. -| Kind | Tests | -| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Every configuration | `hostname`, `kernel`, `nix-system-features`, `security-apparmor`, `security-container-groups`, `security-firewall`, `security-k3s-kubeconfig`, `security-ssh-x11` | -| Named hosts only | `btrbk`, `home-manager`, `home-manager-xdg`, `computer-use-headless`, `k3s-master-home-manager`, `idols-ai-gpu`, `youko-metrics`, `ups-metrics`, `shoukei-logind` | +| Kind | Tests | +| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Every configuration | `hostname`, `kernel`, `nix-system-features`, `security-apparmor`, `security-container-groups`, `security-exporters`, `security-firewall`, `security-k3s-kubeconfig`, `security-kernel`, `security-ssh-x11` | +| Named hosts only | `btrbk`, `home-manager`, `home-manager-xdg`, `computer-use-headless`, `k3s-api-endpoint`, `k3s-master-home-manager`, `idols-ai-gpu`, `youko-metrics`, `ups-metrics`, `shoukei-logind` | `hostname` expects each configuration's `networking.hostName` to equal its name. Niri desktop configurations are the exception (`ai-niri` → `ai`, `shoukei-niri` → `shoukei`) and are listed in @@ -71,7 +71,7 @@ Problems: agenix secrets. - [ ] Maybe it's better to test every service separately, not the whole host? -How to run NixOS tests for every host: +How to run a host's NixOS tests: ```bash # Format: nix build .#-nixos-tests @@ -79,6 +79,8 @@ How to run NixOS tests for every host: nix build .#ruby-nixos-tests ``` +Only `ruby` currently defines a `*-nixos-tests` output. + ## Overview All the outputs of this flake are defined here. diff --git a/secrets/README.md b/secrets/README.md index aa4c01a8..ceefe879 100644 --- a/secrets/README.md +++ b/secrets/README.md @@ -17,8 +17,9 @@ In this way, all secrets are still encrypted when transmitted over the network a In addition, we further improve the security of secret files by storing them in a separate private repository. -This directory contains this `README.md`, and a `nixos.nix`/`darwin.nix` file that is used to -decrypt all my secrets via `agenix`. Then, I can use them in this flake. +This directory contains this `README.md`, the `Justfile` with the agenix recipes, and the +`nixos.nix`/`darwin.nix` files that decrypt all my secrets via `agenix`. Then, I can use them in +this flake. ## Which Keys Go on a Secret @@ -36,7 +37,8 @@ The one exception is the desktop's own restic repository password (`restic-passw ## Decrypted File Permissions -`secrets/nixos.nix` and `secrets/darwin.nix` give every secret one of three presets: +Most secrets in `secrets/nixos.nix` and `secrets/darwin.nix` use one of three shared presets; a few +set `mode`/`owner` inline: | Preset | Mode / owner | Use for | | --------------- | --------------- | ------------------------------------------------ | @@ -55,7 +57,9 @@ every local account. Always set `user` together with `mode`. nix-darwin ignores ## Adding or Updating Secrets -> All the operations in this section should be performed in my private repository: `nix-secrets`. +> The encrypted `.age` files and `secrets.nix` live in my private `nix-secrets` repository. The +> `Justfile` referenced below lives in this repository and runs its recipes with `working-directory` +> set to a local `~/codes/nix-secrets` checkout, so invoke it from this repository's root. This task is accomplished using the [agenix](https://github.com/ryantm/agenix) CLI tool with the `./secrets.nix` file, so you need to have it installed first: @@ -107,7 +111,7 @@ in } ``` -3. Create the secret file `xxx.age` from the repository root with the [`Justfile`](./Justfile) +3. Create the secret file `xxx.age` from this repository's root with the [`Justfile`](./Justfile) `replace` recipe, piping the plaintext on stdin: ```shell @@ -199,7 +203,7 @@ Then, create `./secrets/nixos.nix` (or `./secrets/darwin.nix` on macOS) with the # whether secrets are symlinked to age.secrets..path symlink = true; # target path for decrypted file - path = "/etc/xxx/"; + path = "/etc/xxx"; # encrypted file path file = "${mysecrets}/xxx.age"; # refer to ./xxx.age located in `mysecrets` repo mode = "0400"; diff --git a/vars/README.md b/vars/README.md index 1cd41088..7b82fdc3 100644 --- a/vars/README.md +++ b/vars/README.md @@ -35,12 +35,8 @@ Comprehensive network configuration including: ## Host Categories -The networking configuration covers: - -- **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 +`networking.nix` maps each host to its LAN address and interface. The authoritative inventory is +[`../hosts/README.md`](../hosts/README.md); this file holds only the addresses. ## Usage