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,61 @@
+# kelder
+
+Secondary home server at a remote site, domain `hentai.engineer`. Linked back to colony over
+WireGuard and acting as a NixOS container host (like `shill`/`sfh`).
+
+- **Source:** [`nixos/boxes/kelder/`](../../../nixos/boxes/kelder)
+- **Host:** physical (Intel; LTS kernel, `kvm-intel`, IOMMU on)
+- **nixpkgs:** `mine`
+
+## Role
+
+- **Container host** — runs two NixOS containers on the `ctrs` bridge
+  (`my.containers.instances`): `kelder-acquisition` and `kelder-spoder` (below).
+- **Public services via colony** — a WireGuard tunnel (`estuary` netdev) connects to colony's
+  `estuary` box, which DNATs public traffic to kelder's tunneled assignment; connection-mark-based
+  policy routing sends replies back through the tunnel while ordinary traffic uses the LAN.
+  kelder's own NAT forwards `http`/`https` on to `kelder-spoder`.
+- **Nextcloud host** — served from the `kelder-spoder` container.
+- **Samba** — the `storage` share backed by `/mnt/storage`, with `nmbd` and `samba-wsdd` for
+  Windows discovery.
+- **DDNS** — a `ddns-update` timer runs `dns_update.py` periodically to sync the
+  `hentai.engineer` and `kelder-local.hentai.engineer` Cloudflare records with the address on
+  `et1g0`.
+
+## Network assignments
+
+See the consolidated [network assignments](../../networking.md#box-assignments) table (this box: `kelder`).
+
+## Containers
+
+| Container | Role |
+| --- | --- |
+| [`kelder-acquisition`](containers/kelder-acquisition.md) | Media stack (Transmission over AirVPN, Jackett/Radarr/Sonarr, Jellyfin) |
+| [`kelder-spoder`](containers/kelder-spoder.md) | Nextcloud + nginx reverse proxy |
+
+The containers are not deploy targets (`my.deploy.enable = false`); they're managed through
+the host.
+
+## Networking
+
+- LAN on `et1g0` (renamed by MAC) with DHCP and MTU 1460 (`lib.my.c.kelder.ipv4MTU`); the
+  kelder v4 prefixes are masqueraded out of it.
+- The `estuary` WireGuard peer is combined with rules that keep LAN traffic on the main table and
+  only route tunnel-marked or owned traffic through the tunnel's dedicated table.
+
+## Services
+
+- `netdata` (proxied as `monitor.hentai.engineer` by `kelder-spoder`), `smartd`, `fstrim`,
+  LVM thin provisioning.
+- `minecraft-server` is present but **disabled** (`enable = false`); the firewall still opens
+  25565 tcp/udp.
+- Primary user `kontent` (in the `storage`/`media` groups).
+- Sets `system.nixos.distroName = "KelderOS"`, a custom Plymouth theme and an `amogus-beep`
+  boot jingle ([`boot.nix`](../../../nixos/boxes/kelder/boot.nix)).
+
+## Notable config files
+
+- [`nixos/boxes/kelder/default.nix`](../../../nixos/boxes/kelder/default.nix) — system, assignments, tunnel, NAT, containers.
+- [`nixos/boxes/kelder/boot.nix`](../../../nixos/boxes/kelder/boot.nix) — Plymouth theme + boot beep.
+- [`nixos/boxes/kelder/containers/`](../../../nixos/boxes/kelder/containers) — the two container definitions.
+- [`nixos/boxes/kelder/dns_update.py`](../../../nixos/boxes/kelder/dns_update.py) — Cloudflare DDNS script.
@@ -0,0 +1,45 @@
+# kelder-acquisition
+
+The media acquisition stack for the kelder site — Transmission (forced over VPN), the *arrs
+and Jellyfin in one NixOS container.
+
+- **Source:** [`nixos/boxes/kelder/containers/acquisition/`](../../../../nixos/boxes/kelder/containers/acquisition)
+- **Host:** NixOS container on [`kelder`](../README.md)
+- **nixpkgs:** `mine`
+
+## Role
+
+### Transmission
+
+`transmission_4` is bound to the VPN wait-online unit and uses AirVPN's forwarded peer port. Upload,
+download and seed-ratio limits are configured in the service source. Downloads use
+`/mnt/media/downloads/torrents`, backed by the host's `/mnt/storage/media`.
+
+### Media services
+
+Jackett, Radarr and Sonarr share the `media` group with a group-writable umask. Jellyfin uses the
+host's bind-mounted `/dev/dri` with `intel-vaapi-driver` / `intel-ocl`; its user belongs to
+`render`.
+
+## Network assignments
+
+See the consolidated [network assignments](../../../networking.md#box-assignments) table (this box: `kelder-acquisition`).
+
+## Networking
+
+- `internal` assignment (name `acquisition-ctr`) on the host's `ctrs` bridge, MTU 1460 to
+  match the site WAN.
+- All non-site traffic goes over an AirVPN WireGuard tunnel (`vpn` netdev, AirVPN IE endpoint).
+  Policy rules keep traffic to and from the kelder prefixes on the main table and push everything
+  else through the VPN's dedicated table.
+- An nftables input chain drops new TCP connections from the VPN interface except the
+  Transmission peer port; the web UI ports (9091 Transmission, 9117 Jackett, 7878 Radarr,
+  8989 Sonarr, 8096 Jellyfin) are accepted from the site. When built as a dev VM, those ports
+  are forwarded to the host.
+- Sonarr still needs the EOL .NET 6 runtime, allowed via
+  `nixpkgs.config.permittedInsecurePackages`.
+
+## Notable config files
+
+- [`nixos/boxes/kelder/containers/acquisition/default.nix`](../../../../nixos/boxes/kelder/containers/acquisition/default.nix) — services and users.
+- [`nixos/boxes/kelder/containers/acquisition/networking.nix`](../../../../nixos/boxes/kelder/containers/acquisition/networking.nix) — AirVPN tunnel + firewall.
@@ -0,0 +1,50 @@
+# kelder-spoder
+
+The web container for the kelder site: Nextcloud plus an nginx (OpenResty) reverse proxy for
+the site's services.
+
+- **Source:** [`nixos/boxes/kelder/containers/spoder/`](../../../../nixos/boxes/kelder/containers/spoder)
+- **Host:** NixOS container on [`kelder`](../README.md)
+- **nixpkgs:** `mine`
+
+## Role
+
+- **Nextcloud** (`nextcloud32`) at `cloud.hentai.engineer` (trusted alias
+  `cloud-local.hentai.engineer`), SQLite backend, data in `/mnt/storage/nextcloud`
+  (`/mnt/storage` is bind-mounted from the host).
+- **nginx reverse proxy** (`openresty`) terminating TLS for the site's public vhosts, with a
+  wildcard ACME cert for `hentai.engineer` via Cloudflare DNS. The kelder host forwards
+  `http`/`https` to this container; uploads are unlimited (`clientMaxBodySize = 0`) for
+  Nextcloud's sake.
+
+## Network assignments
+
+See the consolidated [network assignments](../../../networking.md#box-assignments) table (this box: `kelder-spoder`).
+
+## Proxy vhosts
+
+All under `hentai.engineer`, each with a `*-local` alias:
+
+| vhost | Target | Auth |
+| --- | --- | --- |
+| `monitor` | `netdata` on the kelder host (:19999) | `htpasswd` |
+| `kontent` | Jellyfin on `kelder-acquisition` (:8096, incl. websocket) | — |
+| `torrents` | Transmission on `kelder-acquisition` (:9091) | `htpasswd` |
+| `jackett` | Jackett on `kelder-acquisition` (:9117) | `htpasswd` |
+| `radarr` | Radarr on `kelder-acquisition` (:7878) | `htpasswd` |
+| `sonarr` | Sonarr on `kelder-acquisition` (:8989) | `htpasswd` |
+| `cloud` | Nextcloud (local) | — |
+
+An `init_worker_by_lua` timer polls `v4.ident.me` periodically to track the site's public IP; it
+feeds `localRedirect` rewrites (bounce public-IP clients to the `*-local` name) that
+are currently **disabled** (commented out — Virgin Media filters DNS answers containing local
+IPs, so the split doesn't work as intended).
+
+## Networking
+
+- `internal` assignment (name `spoder-ctr`) on the host's `ctrs` bridge, MTU 1420.
+
+## Notable config files
+
+- [`nixos/boxes/kelder/containers/spoder/default.nix`](../../../../nixos/boxes/kelder/containers/spoder/default.nix) — Nextcloud + ACME.
+- [`nixos/boxes/kelder/containers/spoder/nginx.nix`](../../../../nixos/boxes/kelder/containers/spoder/nginx.nix) — reverse proxy vhosts.