updated documentation

.gitea/workflows/check-nixos.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Evaluate all NixOS hosts
         run: |
           set -euo pipefail
-          for host in nixos docker kuma server nix-cache nix-minimal; do
+          for host in nixos docker kuma server nix-cache nix-minimal pxe-boot; do
             echo "Evaluating ${host}"
             nix --extra-experimental-features 'nix-command flakes' eval \
               ".#nixosConfigurations.${host}.config.system.build.toplevel.drvPath" --raw

.github/workflows/check-nixos.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Evaluate all NixOS hosts
         run: |
           set -euo pipefail
-          for host in nixos docker kuma server nix-cache nix-minimal; do
+          for host in nixos docker kuma server nix-cache nix-minimal pxe-boot; do
             echo "Evaluating ${host}"
             nix --extra-experimental-features 'nix-command flakes' eval \
               ".#nixosConfigurations.${host}.config.system.build.toplevel.drvPath" --raw

AGENTS.md

@@ -2,7 +2,8 @@
 
 ## Repo purpose
 
-This repository contains flake-based NixOS configurations for Wayne’s LAN servers and workstation.
+This repository contains flake-based NixOS configurations for Wayne's LAN
+servers and workstation.
 
 The flake currently exposes these NixOS configurations:
 
@@ -12,16 +13,22 @@ The flake currently exposes these NixOS configurations:
 - `server`
 - `nix-cache`
 - `nix-minimal`
+- `pxe-boot`
 
-Do not deploy, switch, reboot, repartition, format disks, or run destructive install commands from this repository unless explicitly asked.
+Do not deploy, switch, reboot, repartition, format disks, or run destructive
+install commands from this repository unless explicitly asked.
 
 ## Safety rules
 
-- Never run `nixos-rebuild switch`, `boot`, `test`, `nixos-install`, `parted`, `mkfs`, `mkswap`, `swapon`, `mount`, or destructive disk commands in Codex.
+- Never run `nixos-rebuild switch`, `boot`, `test`, `nixos-install`, `parted`,
-- Validation work should be limited to evaluation, linting, formatting checks, and `nix build --dry-run --no-link`.
+  `mkfs`, `mkswap`, `swapon`, `mount`, or destructive disk commands in Codex.
-- Do not add secrets, tokens, private keys, password hashes, or live credentials to the repo.
+- Validation work should be limited to evaluation, linting, formatting checks,
+  and `nix build --dry-run --no-link`.
+- Do not add secrets, tokens, private keys, password hashes, or live credentials
+  to the repo.
 - Treat `flake.nix`, Home Manager config, and Nix config files as public.
-- If you find committed tokens or hashes, flag them immediately and recommend rotation/removal.
+- If you find committed tokens or hashes, flag them immediately and recommend
+  rotation/removal.
 
 ## Expected commands
 
@@ -31,3 +38,10 @@ Use these commands when validating changes:
 bash scripts/codex-setup.sh
 bash scripts/codex-maintenance.sh
 bash scripts/codex-maintenance.sh dry-run
+```
+
+Host evaluation is safe when limited to drvPath checks:
+
+```bash
+nix eval .#nixosConfigurations.<host>.config.system.build.toplevel.drvPath --raw
+```

README.md

@@ -1,10 +1,7 @@
-
-## `README.md`
-
-```markdown
 # NixOS LAN Configurations
 
-Flake-based NixOS configuration repository for Wayne’s LAN machines.
+Flake-based NixOS configuration repository for Wayne's LAN servers and
+workstation.
 
 ## Hosts
 
@@ -12,14 +9,64 @@ This flake currently defines:
 
 | Host | Purpose |
 | --- | --- |
-| `nixos` | Main NixOS workstation / desktop |
+| `nixos` | Main NixOS workstation / Cinnamon desktop |
 | `docker` | Docker host for the main container stack |
 | `kuma` | Docker-enabled Uptime Kuma style host |
-| `server` | Storage / NFS / backup style server |
+| `server` | Storage, NFS, backup, and monitoring exporter host |
-| `nix-cache` | Local Nix binary cache host |
+| `nix-cache` | Local Nix binary cache and remote builder |
-| `nix-minimal` | Minimal NixOS host profile |
+| `nix-minimal` | Minimal NixOS host profile with SSHFS tooling |
+| `pxe-boot` | HTTP/iPXE boot asset host |
 
 List hosts with:
 
 ```bash
 nix eval --json .#nixosConfigurations --apply builtins.attrNames | jq -r '.[]'
+```
+
+## Layout
+
+| Path | Purpose |
+| --- | --- |
+| `flake.nix` | Flake inputs and `nixosConfigurations` outputs |
+| `hosts/<host>/configuration.nix` | Host-specific NixOS configuration |
+| `hosts/nixos/home.nix` | Workstation-specific Home Manager config |
+| `common/` | Shared NixOS, Home Manager, aliases, and hardware config |
+| `modules/nix/` | Binary cache and remote builder client/server modules |
+| `docs/` | Operational notes for cache, builders, lock updates, and boot services |
+| `scripts/` | Codex setup and validation helpers |
+
+## Validation
+
+Safe validation commands for Codex and local review:
+
+```bash
+bash scripts/codex-setup.sh
+bash scripts/codex-maintenance.sh dry-run
+bash scripts/codex-maintenance.sh
+```
+
+For individual host evaluation:
+
+```bash
+nix eval .#nixosConfigurations.<host>.config.system.build.toplevel.drvPath --raw
+```
+
+Use `nix build --dry-run --no-link` when build planning is needed. Do not run
+deployment, install, disk formatting, mount, or reboot commands from automated
+review sessions.
+
+## Operations
+
+- Host rebuilds should consume the committed `flake.lock`.
+- Routine dependency updates should happen through the flake lock automation
+  described in `docs/flake-lock-automation.md`.
+- `nix-cache` serves substitutes over HTTP and can act as a remote builder for
+  client hosts.
+- `pxe-boot` serves iPXE boot files over HTTP from `/srv/pxe`.
+
+## Security Notes
+
+Do not commit tokens, private keys, live credentials, or new password hashes.
+This repository currently contains committed password hashes in shared NixOS
+configuration; rotate those passwords and move hashes into host-local secret
+management before treating the repository as public or widely shared.

docs/flake-lock-automation.md

@@ -1,6 +1,7 @@
 # flake.lock automation
 
-This repository uses CI workflows to keep `flake.lock` up to date on a schedule and to verify that all declared NixOS hosts still evaluate after dependency updates.
+This repository uses CI workflows to keep `flake.lock` up to date on a schedule
+and to verify that declared NixOS hosts still evaluate after dependency updates.
 
 ## What this automation does
 
@@ -14,6 +15,7 @@ This repository uses CI workflows to keep `flake.lock` up to date on a schedule
   - `server`
   - `nix-cache`
   - `nix-minimal`
+  - `pxe-boot`
 
 ## Why hosts should stop using `--upgrade-all`
 
@@ -27,6 +29,9 @@ sudo nixos-rebuild switch --flake git+https://gitea.lan.ddnsgeek.com/beatzaplent
 
 Using the committed lock file keeps all hosts aligned and makes updates auditable through CI and code review.
 
+Codex and automated review sessions must not run rebuilds. Limit checks to
+evaluation, linting, formatting, and dry-run builds.
+
 ## Command differences
 
 - `nix flake update`

docs/nix-cache.md

@@ -8,6 +8,8 @@ This repository configures `nix-cache` as a **binary cache server** and a **remo
 - Every machine still keeps and uses its own local `/nix/store`.
 - Clients prefer `http://nix-cache` for substitutes and keep `https://cache.nixos.org/` as fallback.
 - Clients can offload builds to `nix-cache` through SSH (`nix.distributedBuilds`).
+- Client hosts import `modules/nix/cache-client.nix` and, when remote building is enabled, `modules/nix/remote-builder-client.nix`.
+- The `nix-cache` host imports `modules/nix/cache-server.nix`.
 
 ## Binary cache signing keys (on nix-cache)
 
@@ -20,6 +22,8 @@ cat /etc/nix/cache-pub.pem
 ```
 
 Do not commit private keys.
+Do not commit new password hashes or live credentials. Existing committed hashes
+should be rotated and moved to host-local secret management.
 
 ## Remote builder SSH keys
 
@@ -33,6 +37,9 @@ sudo ssh -i /root/.ssh/nixremote nixremote@nix-cache nix-store --version
 
 On `nix-cache`, install the matching public key used by `nixremote` authorized keys.
 
+The committed `nixremote` authorized keys are public SSH keys only. Keep the
+matching private keys on client hosts and out of the repository.
+
 ## Manual verification
 
 After deployment:

docs/pxe-boot.md

@@ -0,0 +1,52 @@
+# pxe-boot
+
+The `pxe-boot` host serves HTTP boot assets for iPXE clients.
+
+## Host Role
+
+- Hostname: `pxe-boot`
+- Web service: nginx on TCP port 80
+- PXE root: `/srv/pxe`
+- Generated iPXE menu: `/srv/pxe/boot/menu.ipxe`
+- Boot binaries copied from the Nix `ipxe` package:
+  - `/srv/pxe/boot/ipxe.efi`
+  - `/srv/pxe/boot/undionly.kpxe`
+
+## Directory Layout
+
+The host creates these directories with systemd tmpfiles:
+
+```text
+/srv/pxe
+/srv/pxe/boot
+/srv/pxe/nixos
+/srv/pxe/ubuntu
+/srv/pxe/rescue
+```
+
+The generated menu currently exposes entries for:
+
+- NixOS installer
+- Rescue environment
+- iPXE shell
+- Reboot
+
+Kernel and initrd artifacts for installer or rescue entries must be placed under
+the matching `/srv/pxe/<entry>/` directories by an operator or a separate build
+process. This repository defines the service and menu, not the installer images.
+
+## Validation
+
+Safe evaluation check:
+
+```bash
+nix eval .#nixosConfigurations.pxe-boot.config.system.build.toplevel.drvPath --raw
+```
+
+After deployment by an operator, basic service checks are:
+
+```bash
+curl http://pxe-boot/boot/menu.ipxe
+curl -I http://pxe-boot/boot/ipxe.efi
+curl -I http://pxe-boot/boot/undionly.kpxe
+```