dev/nixfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: Document the boxes

Browse Source 
Add a top-level `README.md` mapping the boxes and per-machine docs under
`docs/boxes/` (grouped `colony/`, `home/`, `misc/`), one file per host, VM and
container documenting role, services and networking with source pointers.

Also point `AGENTS.md` at the new docs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Jack O'Sullivan
2026-06-14 22:40:13 +01:00
parent 90cc2d53f1
commit a7ea91f529
35 changed files with 986 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/boxes/home/README.md
+44
View File
@@ -0,0 +1,44 @@
# home
The home network. A VM host (`palace`), a redundant pair of routers, a storage
server, Home Assistant, and personal desktops.
- **Domain:** `h.nul.ie`
- **Source:** [`nixos/boxes/home/`](../../../nixos/boxes/home)
## Shape
```
palace (physical VM host)
├── river ──── home router (HA pair with stream)
├── cellar ── NVMe-oF storage server (SPDK)
└── sfh ───── NixOS container host ──┬── hass (Home Assistant)
└── unifi (UniFi controller — defined, currently disabled)
stream ── standalone home router (HA pair with river)
castle ── desktop workstation (boots its disks over NVMe-oF from cellar)
```
The two routers `river` (a VM on `palace`) and `stream` (standalone hardware)
share the [`routing-common`](../../../nixos/boxes/home/routing-common) config and
form a **keepalived/VRRP high-availability pair**: DHCP (kea), router
advertisements (radvd), DNS with blocklists, NAT, and the AS211024 L2 mesh link
back to colony.
## Machines
| Machine | Role | Docs |
| --- | --- | --- |
| `palace` | Physical VM host | [palace.md](palace.md) |
| `river` | Home router (VM; VRRP pair with `stream`) | [river.md](river.md) |
| `cellar` | NVMe-oF storage server (SPDK) | [cellar.md](cellar.md) |
| `sfh` | NixOS container host | [sfh.md](sfh.md) |
| `stream` | Home router (standalone hardware; VRRP pair with `river`) | [stream.md](stream.md) |
| `castle` | Desktop workstation | [castle.md](castle.md) |
### sfh containers
| Container | Role | Docs |
| --- | --- | --- |
| `hass` | Home Assistant | [hass.md](hass.md) |
| `unifi` | UniFi network controller (defined, **currently not imported**) | [unifi.md](unifi.md) |
docs/boxes/home/castle.md
+19
View File
@@ -0,0 +1,19 @@
# castle
A desktop workstation.
- **Source:** [`nixos/boxes/home/castle/default.nix`](../../../nixos/boxes/home/castle/default.nix)
## Role
- AMD desktop running the GUI environment (`my.gui.enable`, Sway / Wayland via
home-manager).
- **Diskless-style boot:** its `/nix`, `/persist` and `/home` are NVMe-oF volumes
served by [`cellar`](cellar.md) (`/dev/nvmeof/{nix,persist,home}`). The
networking is careful not to drop the IP used for the NVMe-oF connection.
- Uses the `my.nvme` module for the NVMe-oF client setup.
## Networking
- Sits on the home network; depends on the high-speed link to `cellar` for its
root storage.
docs/boxes/home/cellar.md
+39
View File
@@ -0,0 +1,39 @@
# cellar
The home storage server. Exports fast NVMe storage over the network so other
machines (notably `castle`) can boot and run from it.
- **Source:** [`nixos/boxes/home/palace/vms/cellar/`](../../../nixos/boxes/home/palace/vms/cellar)
(`default.nix`, `spdk.nix`)
- **Host:** VM on `palace` (NVMe drives passed through)
- **Deploy address:** `192.168.68.80`
## Role
- Runs **SPDK** ([`spdk.nix`](../../../nixos/boxes/home/palace/vms/cellar/spdk.nix)) as
a userspace storage target. The kernel `nvme` driver is blacklisted so SPDK can
drive the NVMe devices directly (attached by PCI BDF).
- Builds a **RAID0** (`NVMeRaid`) across three NVMe drives, partitioned into three
namespaces, and exports each as an **NVMe-oF target over RDMA** (port 4420) on
the high-speed home network — one namespace per consumer:
| Namespace | NQN | Consumer |
| --- | --- | --- |
| `NVMeRaidp1` | `nqn.2016-06.io.spdk:river` | [`river`](river.md) |
| `NVMeRaidp2` | `nqn.2016-06.io.spdk:castle` | [`castle`](castle.md) |
| `NVMeRaidp3` | `nqn.2016-06.io.spdk:sfh` | [`sfh`](sfh.md) |
Each client is pinned by `hostnqn`, so `river`, `castle` and `sfh` all run their
storage off `cellar` over the network.
## Networking
- Exports on the high-speed home network (`lan-hi` / the `hi` assignment) over
RDMA; the SPDK target waits for that link to be online before starting.
## Notes
- The `ublk_*` calls in `my.spdk.debugCommands` are **only a debugging script** —
they let you create a local ublk block device to mount and inspect the RAID on
`cellar` itself. They are **not** how storage is exported to clients; that is the
`nvmf` config above.
docs/boxes/home/hass.md
+18
View File
@@ -0,0 +1,18 @@
# hass
[Home Assistant](https://www.home-assistant.io/) — home automation.
- **Source:** [`sfh/containers/hass.nix`](../../../nixos/boxes/home/palace/vms/sfh/containers/hass.nix)
- **Host:** NixOS container on `sfh`
## Role
- Runs Home Assistant plus supporting services in the container. The `hass-cli`
is wired up against the local server for convenience.
- Integrations/automations are configured here (see commit history for things
like the "West Wood" integration).
## Networking
- `internal` assignment (alt name `hass-ctr`), plus a loopback assignment
(`hass-ctr-lo`) used internally.
docs/boxes/home/palace.md
+21
View File
@@ -0,0 +1,21 @@
# palace (host)
The physical VM host for the home network — the home equivalent of `colony`.
- **Source:** [`nixos/boxes/home/palace/default.nix`](../../../nixos/boxes/home/palace/default.nix)
(VM instances in [`palace/vms/default.nix`](../../../nixos/boxes/home/palace/vms/default.nix))
## Role
- Bare-metal host whose job is to run the home VMs via the `my.vms` module:
`river` (router), `cellar` (storage), `sfh` (container host).
- Provides the bridged networking those VMs sit on and passes through hardware
where needed (e.g. NVMe drives to `cellar`, NICs to `river`).
## VMs hosted here
| VM | Role | Docs |
| --- | --- | --- |
| `river` | Home router (VRRP pair with `stream`) | [river.md](river.md) |
| `cellar` | NVMe-oF storage server | [cellar.md](cellar.md) |
| `sfh` | NixOS container host (Home Assistant, …) | [sfh.md](sfh.md) |
docs/boxes/home/river.md
+25
View File
@@ -0,0 +1,25 @@
# river
One of the two home routers. `river` is a VM on `palace`; it forms a
high-availability pair with the standalone `stream`.
- **Source:** [`nixos/boxes/home/palace/vms/river.nix`](../../../nixos/boxes/home/palace/vms/river.nix),
built from [`routing-common`](../../../nixos/boxes/home/routing-common) (instance `0`)
- **Host:** VM on `palace`
- **Deploy address:** `192.168.68.1`
## Role
Everything in [`routing-common`](../../../nixos/boxes/home/routing-common):
- **VRRP/keepalived** failover with `stream` (`keepalived.nix`) — one router is
master at a time, sharing virtual IPs.
- **DHCP** via kea (`kea.nix`), **router advertisements** via radvd
(`radvd.nix`).
- **DNS** (`dns.nix`) — local resolver with a blocklist
(`dns-blocklist.txt`) and a periodic update script.
- **NAT / firewall** for the home LAN, with policy routing.
- **AS211024 L2 mesh** link back to colony/`estuary` (and the other edge
routers), so home and colony networks interconnect.
See [stream.md](stream.md) for the other half of the pair.
docs/boxes/home/sfh.md
+24
View File
@@ -0,0 +1,24 @@
# sfh
The home **NixOS container host** ("smart from home" / home services).
- **Source:** [`nixos/boxes/home/palace/vms/sfh/`](../../../nixos/boxes/home/palace/vms/sfh)
(`default.nix`, `containers/`)
- **Host:** VM on `palace`
## Role
- Runs the home NixOS containers via `my.containers.instances`, in the same way
`shill` does on colony.
- Sits on the home network and connects to NVMe-oF storage (`cellar`) where
needed.
## Containers
Defined in [`sfh/containers/`](../../../nixos/boxes/home/palace/vms/sfh/containers)
and imported from its `containers/default.nix`:
| Container | Role | Docs |
| --- | --- | --- |
| `hass` | Home Assistant | [hass.md](hass.md) |
| `unifi` | UniFi controller — **defined but currently commented out** of `containers/default.nix` | [unifi.md](unifi.md) |
docs/boxes/home/stream.md
+19
View File
@@ -0,0 +1,19 @@
# stream
One of the two home routers. `stream` is standalone hardware; it forms a
high-availability pair with `river` (a VM on `palace`).
- **Source:** [`nixos/boxes/home/stream.nix`](../../../nixos/boxes/home/stream.nix),
built from [`routing-common`](../../../nixos/boxes/home/routing-common) (instance `1`)
- **Deploy address:** `192.168.68.2`
## Role
- Same [`routing-common`](../../../nixos/boxes/home/routing-common) role as
[`river`](river.md): keepalived/VRRP, kea DHCP, radvd, DNS + blocklist, NAT and
the AS211024 L2 mesh link to colony.
- Additionally pulls in `mstpd` (`routing-common/mstpd.nix`) for spanning-tree on
its bridged ports — `stream` is the one wired into the physical switching, so
it manages the L2 topology.
See [river.md](river.md) for the other half of the pair.
docs/boxes/home/unifi.md
+23
View File
@@ -0,0 +1,23 @@
# unifi
The UniFi network controller.
- **Source:** [`sfh/containers/unifi.nix`](../../../nixos/boxes/home/palace/vms/sfh/containers/unifi.nix)
- **Host:** NixOS container on `sfh`
## Status
> **Currently disabled.** The system is still defined (`nixos.systems.unifi`),
> but its import is commented out in
> [`sfh/containers/default.nix`](../../../nixos/boxes/home/palace/vms/sfh/containers/default.nix),
> so it is not deployed as a container right now. Re-enable by uncommenting
> `./unifi.nix` there.
## Role
- Runs the UniFi controller (`services.unifi`) to manage the home UniFi network
gear.
## Networking
- `internal` assignment (alt name `unifi-ctr`).