docs: Document the boxes

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>
2026-06-14 22:40:13 +01:00
parent 90cc2d53f1
commit a7ea91f529
35 changed files with 986 additions and 2 deletions
@@ -0,0 +1,21 @@
+# misc
+
+Everything that isn't part of the `colony` or `home` sites: the edge VPSes, the
+remote `kelder` site, a workstation, and the installer image.
+
+| Machine | What it is | Docs |
+| --- | --- | --- |
+| `britway` | Vultr VPS (London, `lon1`): Headscale, Tailscale exit node, BGP edge, nginx | [britway.md](britway.md) |
+| `britnet` | VPS (Birmingham, `bhx1`): Tailscale/WireGuard gateway | [britnet.md](britnet.md) |
+| `kelder` | Remote site host (`hentai.engineer`): NixOS container host | [kelder.md](kelder.md) |
+| `tower` | Framework Laptop 13 (12th-gen Intel) workstation | [tower.md](tower.md) |
+| `installer` | Custom NixOS installer image | [installer.md](installer.md) |
+
+## kelder containers
+
+`kelder` is itself a container host (like `shill`/`sfh`):
+
+| Container | Role | Docs |
+| --- | --- | --- |
+| `kelder-acquisition` | Media stack (Jellyfin + *arr + Transmission) | [kelder-acquisition.md](kelder-acquisition.md) |
+| `kelder-spoder` | nginx web host | [kelder-spoder.md](kelder-spoder.md) |
@@ -0,0 +1,21 @@
+# britnet
+
+A VPS in Birmingham (`bhx1`) acting as a Tailscale/WireGuard gateway node.
+
+- **Source:** [`nixos/boxes/britnet.nix`](../../../nixos/boxes/britnet.nix)
+- **Internal domain:** `bhx1.int.nul.ie`
+
+## Role
+
+- **Tailscale node** + **WireGuard** (`wg0`) gateway: provides a second egress /
+  entry point into the boxes' overlay networks.
+- nftables SNATs traffic arriving on `tailscale0` / `wg0` out of the provider
+  interface (`veth0`), using the `allhost` assignment addresses.
+
+## Networking
+
+- Provider uplink with gateways `77.74.199.1` (v4) / `2a12:ab46:5344::1` (v6).
+- `tailscale0` and `wg0` overlay interfaces; `allhost` assignment for SNAT.
+
+> `britnet` is a separate machine from [`britway`](britway.md) — different
+> provider/site, narrower role (gateway rather than control plane + BGP edge).
@@ -0,0 +1,27 @@
+# britway
+
+A Vultr VPS in London (`lon1`) acting as a network edge node: the Tailscale
+control plane, an exit node, and a BGP speaker in the AS211024 mesh.
+
+- **Source:** [`nixos/boxes/britway/`](../../../nixos/boxes/britway)
+  (`default.nix`, `bgp.nix`, `nginx.nix`, `tailscale.nix`)
+- **Internal domain:** `lon1.int.nul.ie`
+
+## Role
+
+- **Headscale** ([`tailscale.nix`](../../../nixos/boxes/britway/tailscale.nix)) — the
+  self-hosted Tailscale control server (`hs.nul.ie`) the rest of the boxes log
+  into.
+- **Tailscale node** — advertises itself as an **exit node** and advertises the
+  tailnet routes, so tailnet clients can egress / reach internal prefixes via
+  britway.
+- **BGP** ([`bgp.nix`](../../../nixos/boxes/britway/bgp.nix)) — part of the AS211024
+  L2 VXLAN mesh (`my.vpns.l2`) alongside `estuary`, `river` and `stream`.
+- **nginx** ([`nginx.nix`](../../../nixos/boxes/britway/nginx.nix)) — reverse proxy /
+  web front-end with ACME certs.
+
+## Networking
+
+- `vultr` assignment on the provider interface; `as211024` on the mesh.
+- A `veth0`/`tailscale0` setup with SNAT so tailnet traffic egresses via the VPS
+  public IP.
@@ -0,0 +1,19 @@
+# installer
+
+The custom NixOS installer image used to bootstrap new boxes.
+
+- **Source:** [`nixos/installer.nix`](../../../nixos/installer.nix)
+
+## Role
+
+- Defines `nixos.systems.installer`, a minimal system whose `my.buildAs.*`
+  outputs produce installable artifacts — primarily a bootable **ISO**
+  (`isoImage`), and the same base is reused for kexec/netboot trees.
+- Build it with the devshell commands (see [`AGENTS.md`](../../../AGENTS.md#commands)):
+  - `build-iso installer`
+  - `build-kexec installer` / `build-netboot installer`
+- A released ISO is what `colony`'s VM definitions reference as install media; the
+  `update-installer` devshell command tags a release to trigger a rebuild.
+
+This is a build target rather than a deployed machine — there is no running
+`installer` host.
@@ -0,0 +1,20 @@
+# kelder-acquisition
+
+The media stack for the `kelder` site — a slimmer cousin of colony's
+[`jackflix`](../colony/jackflix.md).
+
+- **Source:** [`kelder/containers/acquisition/`](../../../nixos/boxes/kelder/containers/acquisition)
+  (`default.nix`, `networking.nix`)
+- **Host:** NixOS container on `kelder`
+
+## Role
+
+- **Jellyfin** for streaming (with hardware transcoding — the `jellyfin` user is
+  in the `render` group, `jellyfin-ffmpeg`).
+- **Acquisition:** Transmission, Jackett, Radarr, Sonarr.
+- Runs under the site's shared `kontent` user.
+
+## Networking
+
+- `internal` assignment (alt name `acquisition-ctr`) on the kelder container
+  network; download client networking in `networking.nix`.
@@ -0,0 +1,17 @@
+# kelder-spoder
+
+An nginx web host on the `kelder` site.
+
+- **Source:** [`kelder/containers/spoder/`](../../../nixos/boxes/kelder/containers/spoder)
+  (`default.nix`, `nginx.nix`)
+- **Host:** NixOS container on `kelder`
+
+## Role
+
+- Serves web content via **nginx** ([`nginx.nix`](../../../nixos/boxes/kelder/containers/spoder/nginx.nix)),
+  with ACME-managed certificates (nginx in the `acme` group, reloads on renewal).
+- Runs under the site's shared `kontent` user.
+
+## Networking
+
+- `internal` assignment (alt name `spoder-ctr`) on the kelder container network.
@@ -0,0 +1,24 @@
+# kelder
+
+A host at a remote site ("kelder" = cellar/basement), linked back to the rest of
+the other boxes over WireGuard. It is itself a **NixOS container host**.
+
+- **Source:** [`nixos/boxes/kelder/`](../../../nixos/boxes/kelder)
+  (`default.nix`, `boot.nix`, `containers/`, `plymouth/`)
+- **Domain:** `hentai.engineer`
+
+## Role
+
+- **Site uplink:** connects to colony's `estuary` over **WireGuard**
+  (`kelder` peer; see [estuary.md](../colony/estuary.md)), so the remote site is
+  reachable through the colony edge. A periodic `dns_update.py` keeps DNS current.
+- **Container host:** runs NixOS containers via `my.containers.instances`
+  (`acquisition`, `spoder`).
+- Custom boot/splash (`boot.nix`, Plymouth theme in `plymouth/`).
+
+## Containers
+
+| Container | Role | Docs |
+| --- | --- | --- |
+| `kelder-acquisition` | Media stack (Jellyfin + *arr + Transmission) | [kelder-acquisition.md](kelder-acquisition.md) |
+| `kelder-spoder` | nginx web host | [kelder-spoder.md](kelder-spoder.md) |
@@ -0,0 +1,16 @@
+# tower
+
+A laptop workstation — a Framework Laptop 13 (12th-gen Intel).
+
+- **Source:** [`nixos/boxes/tower/default.nix`](../../../nixos/boxes/tower/default.nix)
+
+## Role
+
+- Framework Laptop 13 (12th-gen Intel) running the GUI environment
+  (`my.gui.enable`) with home-manager on the `mine` channel.
+- Joins the tailnet via the self-hosted Headscale on [`britway`](britway.md)
+  (`tailscale up --login-server=https://hs.nul.ie --accept-routes`).
+- Local virtualisation enabled (`kvm-intel`, IOMMU on).
+
+> Unlike [`castle`](../home/castle.md), `tower` lives outside the `home/` box
+> tree and boots from local disks rather than NVMe-oF.