docs/boxes: Document deployed boxes

Add per-site and per-box inventories, consolidate shared network design, and relocate the switch and access-point references under the home site.
2026-08-01 23:52:57 +01:00
parent 43cf35d54e
commit a2f3410e42
40 changed files with 2285 additions and 66 deletions
@@ -0,0 +1,45 @@
+# Home site
+
+The home network (domain `h.nul.ie`): a redundant pair of routers in front of a VM host, an
+NVMe-oF storage target, an IoT container host, and a workstation. The two routers — `river` (a VM)
+and `stream` (a physical box) — are built from one shared
+[`routing-common`](../../../nixos/boxes/home/routing-common) definition as an active/backup VRRP
+pair, and everything clients touch (gateway, DNS) is a floating VIP that follows the master.
+
+- **Source:** [`nixos/boxes/home/`](../../../nixos/boxes/home)
+
+## Boxes
+
+| Box | Role | Host |
+|---|---|---|
+| [`palace`](palace.md) | VM host | physical |
+| [`river`](river.md) | Primary router (VRRP pair with `stream`) | VM on `palace` |
+| [`stream`](stream.md) | Secondary router (VRRP pair with `river`) | physical |
+| [`cellar`](cellar.md) | NVMe-oF / SPDK storage target | VM on `palace` |
+| [`sfh`](sfh/README.md) | NixOS container host (containers on its page) | VM on `palace` |
+| [`castle`](castle.md) | Workstation / gaming desktop | physical |
+
+## Router VIPs
+
+Clients use per-VLAN floating VIPs as their gateway and DNS server; `keepalived` moves them between
+`river` and `stream`. The addresses, DHCP/RA behavior and failover mechanics are documented once in
+[Router VIPs](../../networking.md#router-vips) and [Router HA](../../networking.md#router-ha).
+
+## Networks
+
+The site separates core management, high-MTU trusted traffic, general trusted traffic, untrusted
+clients and the two WAN paths. VLAN IDs, prefixes, MTUs and router addressing live in the canonical
+[`home` section of networking.md](../../networking.md#home).
+
+## Switch fabric
+
+The boxes hang off three hand-configured switches — `jim` and `dave` (MikroTik, RouterOS) and
+`brian` (Ubiquiti, UniFi) — which are **not** managed by this flake. The physical topology, VLAN
+map, the Digiweb WAN path (trunked VLAN 10 + PVID 140 at the ONT edge), and the multi-ONT plan are
+documented in [switches.md](switches.md).
+
+## Wireless APs
+
+The Wi-Fi APs — `vibe` (MikroTik cAP ax) and `wave` (Cudy AX3000 on OpenWrt) — are dumb APs, also
+**not** managed by this flake. The shared VLAN-trunk design, SSIDs, per-AP management addressing,
+and the OpenWrt flash/config for `wave` are in [aps.md](aps.md).