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,32 @@
+# colony
+
+The hosted dedicated server in Amsterdam (`ams1`) and the public-facing half of
+the boxes: almost everything reachable from the internet lives here.
+
+- **Internal domain:** `ams1.int.nul.ie` (`lib.my.c.colony.domain`)
+- **Public domain:** `nul.ie` — public services are published as `*.nul.ie`
+- **Source:** [`nixos/boxes/colony/`](../../../nixos/boxes/colony)
+
+## Networking
+
+`colony` separates the host, VMs, `shill` containers and `whale2` OCI workloads onto dedicated
+networks behind [`estuary`](estuary.md), which terminates the public addressing. The canonical
+prefixes and routing overview are in the [`colony` section of networking.md](../../networking.md#colony).
+
+## Boxes
+
+| Box | Role |
+|---|---|
+| [`colony`](colony.md) | Physical VM host (AMD, KVM, LVM-thin, `borgthin` backups → rsync.net) |
+| [`estuary`](estuary.md) | Edge router: WAN, firewall/NAT, DNS, BGP (AS211024), WireGuard |
+| [`shill`](shill/README.md) | NixOS container host (most applications; per-container pages under `shill/`) |
+| [`whale2`](whale2.md) | podman/OCI game-server host |
+| [`git`](git.md) | Gitea + Gitea Actions runner |
+| [`mail`](mail.md) | Debian VM running mailcow (not NixOS) |
+| [`darts`](darts.md) | Third-party/customer VM (not NixOS) |
+
+The applications running on `shill` are listed on its own page — see
+[shill/README.md](shill/README.md#containers).
+
+`mail` and `darts` are host-defined VMs whose guest operating systems are managed out of band; their
+pages document only what this repository controls.
@@ -0,0 +1,110 @@
+# colony
+
+The physical dedicated server in Amsterdam (`ams1`) and the VM host for
+everything at the colony site.
+
+- **Source:** [`nixos/boxes/colony/default.nix`](../../../nixos/boxes/colony/default.nix)
+  (VM instances in [`nixos/boxes/colony/vms/default.nix`](../../../nixos/boxes/colony/vms/default.nix))
+- **Host:** bare metal (this *is* the physical box)
+- **nixpkgs:** `mine-stable`
+
+## Role
+
+Bare-metal AMD host. It does little application work itself — its job is to run
+the VMs and provide them with storage, networking and backups.
+
+### Virtualisation
+
+The `my.vms` module drives QEMU/KVM with `kvm-amd` and IOMMU enabled. Each `my.vms.instances` entry
+becomes a `vm@<name>` systemd service with UEFI, QMP/monitor sockets under `/run/vms/<name>/`, TAP
+networking and optional `hostDevices` passthrough through `vfio-pci`. `estuary` receives the WAN NIC
+this way.
+
+### Storage
+
+All three NVMe SSDs and all four SATA HDDs are physical volumes in one `main` VG. Separate pools
+and standalone RAID LVs keep workloads on the appropriate media:
+
+| Layer | Physical layout | Main consumers |
+|---|---|---|
+| `nvme-tpool` | Thin-pool data is RAID 0 across the three NVMe SSDs; thin metadata is RAID 1 on two of them. The data itself has no redundancy. | Host `/nix` and `/persist`; VM system and persistence disks; fast data LVs such as `minio`, `oci`, `git`, `gitea-actions-cache`, `nix-cache` and `jam` |
+| `hdds-tpool` | Thin-pool data is RAID 5 across the three 12 TB HDDs; thin metadata is RAID 1 on two NVMe SSDs. | `media`, passed to `shill`, and `backup`, mounted by the host at `/mnt/backup` |
+| `darts-media` | Standalone RAID 5 LV spanning all four HDDs. | Bulk storage passed to `darts` |
+| `darts-ext` | Standalone linear LV using the remaining capacity of the 18 TB HDD. | Expansion storage passed to `darts` |
+
+`media` and `backup` are thin-provisioned, so their virtual capacities are not additive physical
+capacity and overcommit `hdds-tpool`. VM disks built with `lib.my.vm.disk` are named
+`vm-<name>-<disk>` in `main`; `lib.my.vm.lvmDisk` attaches the named data LVs.
+
+The initrd activates only `colony-nix` and `colony-persist`. This avoids checking and activating all
+of the storage before switching root; `lvm-activate-main.service` activates the remaining LVs before
+local filesystems and VMs need them.
+
+### Backups
+
+`my.borgthin` job `main` snapshots host and VM persistence/data LVs into `/mnt/backup/main`.
+`borgthin-rsync.service` copies the repository to rsync.net and `rsync-lvm-meta.service` sends the
+LVM metadata; both run at idle priority after the Borg job.
+
+### Monitoring
+
+Netdata uses FreeIPMI while ignoring the VCCM sensor. The box also runs `smartd` with logs under
+`/var/log/smartd`, `rasdaemon`, and `fstrim` before the backup job.
+
+## Network assignments
+
+See the consolidated [network assignments](../../networking.md#box-assignments) table (this box: `colony`).
+
+## Hardware
+
+| Component | Inventory |
+|---|---|
+| Platform | ASRock Rack X570D4U server board |
+| CPU | AMD Ryzen 9 5950X (16 cores / 32 threads) |
+| Memory | 128 GiB |
+| NVMe storage | Three 2 TB Samsung SSD 980 PRO devices providing the NVMe-backed LVM thin pool and data LVs |
+| Bulk storage | Three 12 TB WD120EDBZ disks and one 18 TB WD180EDGZ disk for the bulk LVM volumes |
+| Boot | SanDisk USB device holding the EFI system partition |
+| Network / management | Two Intel I210 Gigabit Ethernet controllers, one passed through to `estuary`; ASPEED BMC graphics and console |
+
+## Networking
+
+- Two bridges: `base` (the colony base network, shared with `estuary`) and
+  `vms` (the VM network). Dummy interfaces (`base0`, `vms0`) keep the bridges
+  up in networkd's eyes so dependent VMs can start.
+- `colony` sends RAs on `vms` (DNS = `estuary`'s base address) and carries
+  static routes for the downstream prefixes: `ctrs` via `shill`, `oci` via
+  `whale2`, plus the Tailscale, `qclk` and `jam` prefixes via `shill`.
+- `estuary` is the default gateway (via the `base` bridge); `colony`'s own public-facing address is
+  its `internal` assignment (alt name `vm`).
+- The customer VMs attach to dedicated TAP devices (`vm-mail`, `vm-darts`)
+  which are **not** bridged: networkd puts the point-to-point /32
+  (`lib.my.c.colony.custRouting`) and the customer's IPv6 /64 on each, sends
+  RAs, and link-routes the customer's public /32 down the tap.
+- `my.firewall` trusts the `vms` bridge, DNATs the shared
+  `lib.my.c.colony.firewallForwards` list for traffic addressed to `estuary`'s
+  public IP (so the port forwards also work from inside), and forwards the
+  customer prefixes through with minimal filtering ("trust for now").
+
+## VMs
+
+Declared in `my.vms.instances` (`cpus`/`threads` are QEMU `smp` values):
+
+| VM | Cores | Threads | Memory | Network | Disks |
+|---|---|---|---|---|---|
+| `estuary` | 2 | 2 | 3 GiB | `base` | `esp` / `nix` / `persist` LVs + WAN NIC passthrough |
+| `shill` | 12 | 2 | 40 GiB | `vms` | `esp` / `nix` / `persist` + `media` / `minio` / `nix-cache` / `jam` LVs |
+| `whale2` | 8 | 2 | 16 GiB | `vms` | `esp` / `nix` / `persist` + `oci` LV |
+| `git` | 12 | 2 | 40 GiB | `vms` | `esp` / `nix` / `persist` / `oci` + `git` / `gitea-actions-cache` LVs |
+| `mail` | 3 | 2 | 6 GiB | `vm-mail` tap | `root` / `data` LVs |
+| `darts` | 4 | 2 | 16 GiB | `vm-darts` tap | `root` LV + `darts-media` / `darts-ext` LVs |
+
+`estuary`, `shill`, `whale2` and `git` are NixOS systems with their own pages
+(see the [README](README.md#boxes)); [`mail`](mail.md) and [`darts`](darts.md) have host-side
+definitions here, but their guest operating systems are managed out of band.
+
+## Notable config files
+
+- [`nixos/boxes/colony/default.nix`](../../../nixos/boxes/colony/default.nix) — host hardware, networkd, firewall, backups.
+- [`nixos/boxes/colony/vms/default.nix`](../../../nixos/boxes/colony/vms/default.nix) — `my.vms.instances` for all six VMs.
+- [`nixos/modules/vms.nix`](../../../nixos/modules/vms.nix) — the `my.vms` module itself.
@@ -0,0 +1,37 @@
+# darts
+
+An opaque third-party/customer VM. Declared in `colony`'s `my.vms.instances`
+but **not a NixOS system**: this repo knows nothing about what runs inside it
+and doesn't manage it.
+
+- **Source (host-side only):** the `darts` instance in
+  [`nixos/boxes/colony/vms/default.nix`](../../../nixos/boxes/colony/vms/default.nix)
+  and the `90-vm-darts` network in
+  [`nixos/boxes/colony/default.nix`](../../../nixos/boxes/colony/default.nix)
+- **Host:** VM on `colony`
+- **nixpkgs:** not applicable (unmanaged guest; host-side definition uses `colony`'s `mine-stable`)
+
+## Role
+
+- Customer/dedicated VM, left alone beyond hosting and connectivity.
+- A thin-provisioned `root` LV on the NVMe pool, plus `darts-media` (RAID 5 across the four HDDs)
+  and `darts-ext` (linear storage on the 18 TB HDD) in the `main` VG. See
+  [`colony`'s storage layout](colony.md#storage).
+
+## Network assignments
+
+This guest is not a NixOS system, so its host-routed addresses are not rows in the generated
+[network assignments](../../networking.md#box-assignments) table.
+
+- Same customer-VM pattern as [`mail`](mail.md): dedicated unbridged TAP
+  (`vm-darts`), point-to-point address
+  (`custRouting.darts-vm`) on the host side, link-routed public /32
+  `94.142.242.255`, and the IPv6 /64 `2a0e:97c0:4d2:2001::/64` with RAs.
+- DNS: `darts-cust.ams1.int.nul.ie`. Like the other customer prefixes, its
+  inbound traffic is accepted by `estuary` without per-port filtering and
+  forwarded on by `colony`.
+
+## Notable config files
+
+- [`nixos/boxes/colony/vms/default.nix`](../../../nixos/boxes/colony/vms/default.nix) — VM definition.
+- [`nixos/boxes/colony/default.nix`](../../../nixos/boxes/colony/default.nix) — host-side network and routing.
@@ -0,0 +1,164 @@
+# estuary
+
+The colony edge router and firewall — the box that holds colony's public IPs
+and connects everything else at the site to the internet.
+
+- **Source:** [`nixos/boxes/colony/vms/estuary/`](../../../nixos/boxes/colony/vms/estuary)
+  (`default.nix`, `bgp.nix`, `dns.nix`, `bandwidth.nix`)
+- **Host:** VM on `colony` (gets the WAN NIC by PCI passthrough)
+- **nixpkgs:** `mine`
+
+## Role
+
+- **Edge routing / firewall / NAT** — owns the colony public IPv4/IPv6 assignments, NATs outbound
+  traffic, and port-forwards inbound services (see [Firewall and NAT](#firewall-and-nat)).
+- **DNS** — PowerDNS authoritative server *and* recursor (see [DNS](#dns)).
+- **BGP** — BIRD2 speaking AS211024 with upstreams, IXP route servers and
+  direct peers (see [BGP](#bgp)).
+- **VPNs** — the `as211024` L2 VXLAN mesh plus three point-to-point WireGuard
+  tunnels (see [VPNs](#vpns)).
+- **Misc** — `iperf3` server, netdata.
+
+## Network assignments
+
+See the consolidated [network assignments](../../networking.md#box-assignments) table (this box: `estuary`).
+
+## WAN and IXP VLANs
+
+- `wan` — the passed-through `igb` NIC (9000 MTU, enlarged rings). It carries
+  the plain upstream uplink (static v4/v6 with gateways from the `internal`
+  assignment) plus the tagged `ifog` VLAN.
+- `ifog` (VLAN 409) is an iFog QinQ transport that carries the IXP VLANs as
+  nested tags:
+
+| Interface | VLAN | IPv4 | IPv6 | Purpose |
+|---|---|---|---|---|
+| `frys-ix` | 701 | `185.1.160.196/23` | `2001:7f8:10f::3:3850:196/64` | Frys-IX peering LAN |
+| `nl-ix` | 1845 | `193.239.116.145/22` | `2001:7f8:13::a521:1024:1/64` | NL-ix peering LAN |
+| `fogixp` | 1147 | `185.1.147.159/24` | `2001:7f8:ca:1::159/64` | FogIXP peering LAN |
+| `ifog-transit` | 702 | — | `2a0c:9a40:100f:370::2/64` | iFog IPv6 transit |
+
+The IXP interfaces run at 1500 MTU with DHCP/RA/LLDP off; an nftables `ixp`
+chain rejects non-IP/ARP ethertypes in both directions.
+
+- `base` — colony base network; sends RAs and serves DNS to the site, and
+  routes the `vms`/`ctrs`/`oci`, Tailscale, `qclk`, `vip*` and customer
+  prefixes back via `colony`.
+- `as211024` — the L2 mesh interface (see VPNs).
+
+## Firewall and NAT
+
+`my.firewall` (nftables). Inbound port forwards (`my.firewall.nat.forwardPorts`,
+driven by the shared `lib.my.c.colony.firewallForwards` list):
+
+| Service | Forwarded to |
+|---|---|
+| HTTP/S, Matrix federation | `middleman` |
+| Git | `git` |
+| Game servers | OCI servers on `whale2`, `gam` |
+| Tailscale | `waffletail` |
+| `qclk` WireGuard | `qclk` |
+
+Besides the forwards, `extraRules` defines:
+
+- `routing-tcp` / `routing-udp` chains — the inbound allow-list for new
+  connections from `wan`/`as211024`/IXPs towards internal services (SSH
+  anywhere, otherwise per-service v4/v6 rules mirroring `firewallForwards`).
+- `filter-routing` — applied to `wan`/`as211024`/IXPs → `base` forwards;
+  customer prefixes (`mail`/`darts` v4, `cust.v6`) are accepted wholesale, the
+  rest goes through the `routing-*` chains.
+- SNAT: everything from `prefixes.all.v4` leaving non-`as211024` interfaces is
+  NATed to the public IP; the WireGuard tunnel prefixes get their own SNAT
+  addresses.
+- DNS redirect: DNS traffic arriving at estuary's own public addresses is
+  redirected to port 5353 (the authoritative server) — see below.
+
+## DNS
+
+Both halves are PowerDNS ([`dns.nix`](../../../nixos/boxes/colony/vms/estuary/dns.nix)).
+
+### Authoritative
+
+`my.pdns.auth`, listening on `0.0.0.0:5353` / `[::]:5353`. Primary for
+`ams1.int.nul.ie`, `100.10.in-addr.arpa` and the `2a0e:97c0:4d2::/48` reverse
+zone.
+
+- Zone contents are largely generated from `allAssignments`
+  (`lib.my.dns.fwdRecords` / `ptrRecords` / `ptr6Records`); `ALIAS` records
+  (with `expand-alias`) point the zone apex at estuary itself.
+- AXFR is allowed to HE.net's secondary (`216.218.133.2` / `2001:470:600::2`).
+- `_acme-challenge` is a LUA `TXT` record answered from a file (DNS-01 issuance).
+- Reached publicly via the NAT redirect of port 53 → 5353; the `base` side also
+  accepts DNS directly.
+
+### Recursor
+
+`my.pdns.recursor` (`pdns-recursor`), listening on localhost and the `base`
+addresses, serving `prefixes.all` and the Tailscale prefixes.
+
+- Authoritative zones are forwarded back to `127.0.0.1:5353` (with NOTIFY
+  support, so changes show up immediately).
+- A small Lua `preresolve` hook rewrites `nix-cache.nul.ie` →
+  `http.ams1.int.nul.ie` so cache traffic stays on-site.
+
+## BGP
+
+BIRD2 ([`bgp.nix`](../../../nixos/boxes/colony/vms/estuary/bgp.nix)) speaking **AS211024**:
+
+| Peer | ASN | Role | Where / notes |
+|---|---|---|---|
+| ColoClue | AS8283 | Upstream | `euNetworks` 2/3, v4+v6 |
+| iFog | AS34927 | Upstream | IPv6 transit |
+| Hurricane Electric | AS6939 | Upstream | IPv6 over Frys-IX |
+| Frys-IX | AS56393 | IXP route server | |
+| NL-ix | AS34307 | IXP route server | lower preference |
+| FogIXP | AS47498 | IXP route server | |
+| LUJE.net | AS212855 | Direct peer | ColoClue/Frys-IX/FogIXP + multihop labs |
+| jurrian | AS212635 | Direct peer | |
+| Meta | AS32934 | Direct peer | Frys-IX/NL-ix |
+| Cloudflare | AS13335 | Direct peer | Frys-IX |
+| Apple | AS714 | Direct peer | NL-ix |
+| HE | AS6939 | Direct peer | Frys-IX (v4) |
+| bgp.tools | AS212232 | Monitoring | multihop collector, `add paths` |
+
+Statics originate the site prefixes: the `vip*` ranges via `base`, the
+ams1/internal v6 prefixes via `base`/`as211024`, and the home /48 towards the
+home routers' `as211024` VIP.
+
+Currently disabled (commented out): efero transit over FogIXP ("not working so
+well lately") and the NL-ix Cloudflare sessions.
+
+## VPNs
+
+### `as211024` L2 mesh
+
+Member alongside `river`/`stream`/`britway` (`my.vpns.l2`, the `l2mesh` module).
+The mesh transport, crypto and addressing are shared fabric — see
+[The AS211024 L2 mesh](../../networking.md#the-as211024-l2-mesh) in networking.md.
+
+### WireGuard tunnels
+
+Point-to-point tunnels terminated here as networkd `wireguard` netdevs (private
+keys from agenix); each SNATs out its own interface address:
+
+| Tunnel | Port | Prefix | Notes |
+|---|---|---|---|
+| `kelder` | 51820 | — | to the remote `kelder` site; kelder's public `estuary` assignment is routed over the tunnel |
+| `hillcrest` | 51822 | `prefixes.hillcrest.v4` (`10.100.5.0/30`) | /32 pair, estuary `.1` ↔ remote `.2` |
+| `john-valorant` | 51823 | `prefixes.john-valorant.v4` (`10.100.5.4/30`) | /32 pair, estuary `.1` ↔ remote `.2` |
+
+## Bandwidth management
+
+[`bandwidth.nix`](../../../nixos/boxes/colony/vms/estuary/bandwidth.nix) implements a WAN shaper: a
+token-bucket filter on `wan` (outbound) and on an `ifb-wan` IFB device that ingress traffic is
+mirrored into (inbound), with
+[`bandwidth.py`](../../../nixos/boxes/colony/vms/estuary/bandwidth.py) as a `bandwidth-limiter`
+service that watches utilisation and can adjust the configured rate. **Currently disabled** — the
+file is not in estuary's `imports` (only `dns.nix` and `bgp.nix` are), so no shaping is applied.
+
+## Notable config files
+
+- [`nixos/boxes/colony/vms/estuary/default.nix`](../../../nixos/boxes/colony/vms/estuary/default.nix) — system, networkd, firewall, WireGuard, mesh membership.
+- [`nixos/boxes/colony/vms/estuary/bgp.nix`](../../../nixos/boxes/colony/vms/estuary/bgp.nix) — BIRD2 config.
+- [`nixos/boxes/colony/vms/estuary/dns.nix`](../../../nixos/boxes/colony/vms/estuary/dns.nix) — PowerDNS auth + recursor.
+- [`nixos/boxes/colony/vms/estuary/bandwidth.nix`](../../../nixos/boxes/colony/vms/estuary/bandwidth.nix) — WAN shaper (disabled, not imported).
@@ -0,0 +1,61 @@
+# git
+
+The Gitea VM — source hosting and CI for the boxes (`git.nul.ie`).
+
+- **Source:** [`nixos/boxes/colony/vms/git/`](../../../nixos/boxes/colony/vms/git)
+  (`default.nix`, `gitea.nix`, `gitea-actions.nix`)
+- **Host:** VM on `colony`
+- **nixpkgs:** `mine`
+
+## Role
+
+### Gitea
+
+The Git forge at `git.nul.ie` (self-registration disabled), configured in
+[`gitea.nix`](../../../nixos/boxes/colony/vms/git/gitea.nix).
+
+- Backed by PostgreSQL on [`colony-psql`](shill/containers/colony-psql.md) (waited on via
+  `lib.my.systemdAwaitPostgres`).
+- LFS enabled; all object storage (incl. LFS and packages) is on MinIO at `s3.nul.ie` (bucket
+  `gitea`, on [`object`](shill/containers/object.md)) — the secret is spliced into `app.ini` at
+  startup.
+- Mail goes out via `mail.nul.ie`, including the issue-reply incoming-mail poller.
+
+### Gitea Actions runner
+
+One Docker-mode instance (`main-docker`) on podman (privileged, `podman` network), configured in
+[`gitea-actions.nix`](../../../nixos/boxes/colony/vms/git/gitea-actions.nix).
+
+- Labels for `node:24-trixie` and the self-built `git.nul.ie/dev/actions-ubuntu:26.04` images.
+- Runs as a fixed `gitea-runner` user (not `DynamicUser`) so it can read its token; jobs have a
+  configured timeout.
+- The action cache lives on a dedicated disk (`/var/cache/gitea-runner`).
+- Executes the repo's own `.gitea/workflows/ci.yaml`.
+
+### nginx
+
+Terminates TLS for `git.nul.ie` (and a default vhost) and proxies to Gitea on `:3000`. ACME
+(Let's Encrypt, production) issues `nul.ie` + `*.nul.ie` via the Cloudflare DNS-01 challenge.
+
+### podman
+
+Local container backend for the runner; `/var/lib/containers` is an XFS data disk, and the default
+`10.88.0.0/16` podman subnet is allowed to forward.
+
+## Network assignments
+
+See the consolidated [network assignments](../../networking.md#box-assignments) table (this box: `git`).
+
+## Storage
+
+- `/var/lib/gitea` — the `git` LV (repositories, config).
+- `/var/cache/gitea-runner` — the `gitea-actions-cache` LV.
+- `/var/lib/containers` — the `oci` LV (XFS with project quotas). Despite the
+  name this is local to the `git` VM and unrelated to `whale2`'s `oci`
+  network.
+
+## Notable config files
+
+- [`nixos/boxes/colony/vms/git/default.nix`](../../../nixos/boxes/colony/vms/git/default.nix) — VM config, nginx + ACME, podman, firewall.
+- [`nixos/boxes/colony/vms/git/gitea.nix`](../../../nixos/boxes/colony/vms/git/gitea.nix) — Gitea itself.
+- [`nixos/boxes/colony/vms/git/gitea-actions.nix`](../../../nixos/boxes/colony/vms/git/gitea-actions.nix) — the Actions runner.
@@ -0,0 +1,45 @@
+# mail
+
+A Debian VM running [mailcow](https://mailcow.email/) (`mail.nul.ie`) — the
+mail server for `nul.ie`. Declared in `colony`'s `my.vms.instances` but **not
+a NixOS system**: everything inside the VM is configured out of band.
+
+- **Source (host-side only):** the `mail` instance in
+  [`nixos/boxes/colony/vms/default.nix`](../../../nixos/boxes/colony/vms/default.nix)
+  and the `90-vm-mail` network in
+  [`nixos/boxes/colony/default.nix`](../../../nixos/boxes/colony/default.nix)
+- **Host:** VM on `colony`
+- **nixpkgs:** not applicable (Debian guest; host-side definition uses `colony`'s `mine-stable`)
+
+## Role
+
+- Runs the full mailcow stack (Postfix/Dovecot/SOGo/Rspamd) for `nul.ie`.
+  Other colony services send through it as `mail.nul.ie` (e.g. Gitea, and the
+  disabled Mastodon config).
+- `root` and `data` LVM disks; the `vm-mail-data` LV is included in `colony`'s `borgthin` backups.
+
+## Network assignments
+
+This guest is not a NixOS system, so its host-routed addresses are not rows in the generated
+[network assignments](../../networking.md#box-assignments) table.
+
+### Link and addressing
+
+The VM attaches to a dedicated, unbridged TAP (`vm-mail`). `colony` puts the point-to-point
+`custRouting.mail-vm` address on the host side, link-routes public
+`94.142.241.227/32` down the TAP, and advertises `2a0e:97c0:4d2:2000::/64` with RAs.
+
+- DNS: `mail-vm.ams1.int.nul.ie` (and `mail.nul.ie` publicly, incl. the PTR in
+  estuary's reverse zone). `estuary` accepts traffic to the customer prefixes
+  without per-port filtering; `colony` forwards it on ("trust for now").
+
+## Notes
+
+- ACME certificates are issued on `middleman` and pushed to the VM over SSH
+  (`acme@mail.nul.ie mailcow-ssl-reload`, key `middleman/mailcow-ssh.key`);
+  the VM's SSH host key is pinned at `.keys/mail-vm-host.pub`.
+
+## Notable config files
+
+- [`nixos/boxes/colony/vms/default.nix`](../../../nixos/boxes/colony/vms/default.nix) — VM definition.
+- [`nixos/boxes/colony/default.nix`](../../../nixos/boxes/colony/default.nix) — host-side network and routing.
@@ -0,0 +1,84 @@
+# shill
+
+The colony NixOS container host — most colony applications run as
+`systemd-nspawn` containers on this VM.
+
+- **Source:** [`nixos/boxes/colony/vms/shill/`](../../../../nixos/boxes/colony/vms/shill)
+  (`default.nix`, `containers-ext.nix`, `containers/`)
+- **Host:** VM on `colony`
+- **nixpkgs:** `mine`
+
+## Role
+
+### Container hosting
+
+`my.containers.instances` runs the colony containers on the `ctrs` bridge. Each is a full NixOS
+system rendered through `my.asContainer` and deployed as a profile on `shill`; containers are not
+standalone deploy targets. The shared container module supplies the nspawn units, `/persist` and
+store binds.
+
+### Shared storage
+
+LVM-backed host volumes are bind-mounted into the consumers: `/mnt/media` is read-only in
+`middleman` and read-write in `jackflix`; `/mnt/minio` and `/mnt/nix-cache` are read-write in
+`object`.
+
+### Routing
+
+`shill` routes between `vms` and `ctrs`, advertises `estuary` as DNS on `ctrs`, and routes Tailscale
+through `waffletail` and the `qclk` prefix through `qclk`. It applies the shared `firewallForwards`
+DNAT for `estuary`'s public IP; a connection-mark-based SNAT rule keeps replies symmetric.
+
+### Host tuning
+
+The box has a larger conntrack table and ephemeral-port range for high connection counts. Netdata
+listens on port 19999.
+
+## Network assignments
+
+See the consolidated [network assignments](../../../networking.md#box-assignments) table (this box: `shill`).
+
+## Containers
+
+Defined under
+[`shill/containers/`](../../../../nixos/boxes/colony/vms/shill/containers) and
+wired up in `shill`'s `my.containers.instances`. The generated
+[network assignments](../../../networking.md#box-assignments) table is the source of truth for
+their current addresses. Each container has its own page:
+
+| Container | Role |
+|---|---|
+| [`middleman`](containers/middleman.md) | Reverse proxy, ACME, nginx-sso, librespeed |
+| [`vaultwarden`](containers/vaultwarden.md) | Password manager |
+| [`colony-psql`](containers/colony-psql.md) | Shared PostgreSQL (14) |
+| [`chatterbox`](containers/chatterbox.md) | Matrix Synapse + bridges |
+| [`jackflix`](containers/jackflix.md) | Media stack |
+| [`object`](containers/object.md) | MinIO, Harmonia Nix cache, Sharry, HedgeDoc, wastebin |
+| [`toot`](containers/toot.md) | Bluesky PDS (Mastodon disabled) |
+| [`waffletail`](containers/waffletail.md) | Tailscale subnet router / exit node |
+| [`qclk`](containers/qclk.md) | WireGuard management appliance |
+| [`gam`](containers/gam.md) | Terraria server |
+
+### `jam`
+
+A one-off: [`containers-ext.nix`](../../../../nixos/boxes/colony/vms/shill/containers-ext.nix)
+runs a raw `systemd-nspawn` container (not a `my.containers` instance, not
+NixOS) with its root on the `jam` LV, private user namespaces and a `ve-jam`
+veth. It gets the `jam` customer prefix (`prefixes.jam`, `jam-cust` in DNS)
+and SSH is forwarded to it from `shill`'s public IP port 60022.
+
+## Notes
+
+- `nix.settings.substituters` is forced to just `https://cache.nixos.org` —
+  `shill` sits next to the S3 cache on `object`, so it doesn't use it.
+- [`hercules.nix`](../../../../nixos/boxes/colony/vms/shill/hercules.nix)
+  (Hercules CI agent + the `nix-cache-gc` timer for the S3 binary cache)
+  exists but is **currently disabled**: the file is not imported by
+  `shill/default.nix`.
+
+## Notable config files
+
+- [`nixos/boxes/colony/vms/shill/default.nix`](../../../../nixos/boxes/colony/vms/shill/default.nix) — VM config, networkd, firewall, `my.containers.instances`.
+- [`nixos/boxes/colony/vms/shill/containers/default.nix`](../../../../nixos/boxes/colony/vms/shill/containers/default.nix) — container imports.
+- [`nixos/boxes/colony/vms/shill/containers-ext.nix`](../../../../nixos/boxes/colony/vms/shill/containers-ext.nix) — the `jam` nspawn container.
+- [`nixos/modules/containers.nix`](../../../../nixos/modules/containers.nix) — the `my.containers` module.
@@ -0,0 +1,41 @@
+# chatterbox
+
+The Matrix homeserver for `nul.ie` (Synapse) and its bridges to other chat networks.
+[middleman](middleman.md) fronts it as `matrix.nul.ie` for clients and on `:8448` for
+federation.
+
+- **Source:** [`shill/containers/chatterbox.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/chatterbox.nix)
+- **Host:** NixOS container on [`shill`](../README.md)
+- **nixpkgs:** `mine`
+
+## Role
+
+### Synapse
+
+`matrix-synapse` serves `nul.ie` at `https://matrix.nul.ie`, with Element at `element.nul.ie`.
+Port 8008 carries client and federation traffic with forwarded headers, while a localhost manhole
+uses port 9000. Registration and guest access are disabled; uploads, dynamic thumbnails and URL
+previews are enabled, with preview fetching restricted to [middleman](middleman.md).
+
+### Bridges
+
+The box runs heisenbridge for IRC, `mautrix-whatsapp`, and two `mautrix-meta` instances for
+Messenger and Instagram. The mautrix bridges use [colony-psql](colony-psql.md), default to
+end-to-end encryption, and share the secret `doublepuppet.yaml` registration for double puppeting
+onto `nul.ie`. The firewall admits ports 8008 and 8009 in addition to netdata.
+
+## Network assignments
+
+See the consolidated [network assignments](../../../../networking.md#box-assignments) table (this box: `chatterbox`).
+
+## Notes
+
+- Synapse's real database config lives in the `chatterbox/synapse.yaml` age secret — options
+  only merge at the top level, so the base config carries a dummy `sqlite3` block to satisfy
+  the module defaults. The signing key is also an age secret.
+- `olm-3.2.16` is allowed via `permittedInsecurePackages` (a nixpkgs E2EE library issue).
+- The bridge services get `ffmpeg` on their `PATH` for GIF→video conversion.
+
+## Notable config files
+
+- [`nixos/boxes/colony/vms/shill/containers/chatterbox.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/chatterbox.nix) — container definition, Synapse settings and all bridge configuration
@@ -0,0 +1,39 @@
+# colony-psql
+
+The shared PostgreSQL instance for colony services. Rather than each service running its own
+database, the containers (and the `git` VM) connect here over the `ctrs` network.
+
+- **Source:** [`shill/containers/colony-psql.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/colony-psql.nix)
+- **Host:** NixOS container on [`shill`](../README.md)
+- **nixpkgs:** `mine`
+
+## Role
+
+- **PostgreSQL 14** with TCP/IP enabled, reachable from the whole colony address space using `md5`
+  authentication. The firewall allows `5432`.
+- Local `peer` auth maps `postgres`, `root`, `netdata` and `dev` to the `postgres` superuser via
+  the ident map.
+- **netdata** with the Python PostgreSQL collector.
+- Consumers wait for the database to accept connections with the `lib.my.systemdAwaitPostgres`
+  helper (e.g. `sharry`, `atticd`, `mastodon-init-db`, and `middleman`'s nginx as a DNS
+  bootstrap hack).
+
+## Network assignments
+
+See the consolidated [network assignments](../../../../networking.md#box-assignments) table (this box: `colony-psql`).
+
+The assignment also has the alt name `colony-psql` (no `-ctr` suffix), which is what consumers
+use as the database hostname.
+
+## Consumers
+
+- [object](object.md) — `sharry` and `hedgedoc` (and `atticd` when enabled) over
+  `colony-psql:5432`
+- [toot](toot.md) — Mastodon's database (Mastodon currently disabled)
+- [chatterbox](chatterbox.md) — the mautrix bridges (WhatsApp, Messenger, Instagram) via
+  Postgres URIs in their secret env files
+- `git` VM — Gitea
+
+## Notable config files
+
+- [`nixos/boxes/colony/vms/shill/containers/colony-psql.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/colony-psql.nix) — container definition and PostgreSQL configuration
@@ -0,0 +1,29 @@
+# gam
+
+A game-server container currently dedicated to Terraria.
+
+- **Source:** [`shill/containers/gam.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/gam.nix)
+- **Host:** NixOS container on [`shill`](../README.md)
+- **nixpkgs:** `mine`
+
+## Role
+
+Runs lightweight game servers directly as NixOS services, rather than as OCI containers on
+[`whale2`](../../whale2.md).
+
+## Network assignments
+
+See the consolidated [network assignments](../../../../networking.md#box-assignments) table (this box: `gam`).
+
+## Terraria server
+
+`services.terraria` runs the dedicated server with its world at
+`/var/lib/terraria/NotWorld.wld`. It creates large worlds automatically, uses the MOTD
+"sup gamers", and disables UPnP. Additional settings such as the password come from the
+`gam/terraria.conf` age secret used as the service configuration file.
+
+`openFirewall` is enabled, and `estuary` forwards TCP and UDP port `7777` to the container.
+
+## Notable config files
+
+- [`nixos/boxes/colony/vms/shill/containers/gam.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/gam.nix) — container definition and the Terraria service
@@ -0,0 +1,56 @@
+# jackflix
+
+The media stack — acquisition, library, streaming and photos. Torrent traffic is routed through
+an AirVPN WireGuard tunnel so downloads only flow while the VPN is up.
+
+- **Source:** [`shill/containers/jackflix/`](../../../../../nixos/boxes/colony/vms/shill/containers/jackflix)
+  (`default.nix`, `networking.nix`)
+- **Host:** NixOS container on [`shill`](../README.md) (bind-mounts `/mnt/media` read-write)
+- **nixpkgs:** `mine`
+
+## Role
+
+| Service | Port | Purpose |
+| --- | --- | --- |
+| Jellyfin | `8096` | streaming, published as `jackflix.nul.ie` |
+| Transmission | `9091` | BitTorrent client (`transmission_4`), published as `torrents.nul.ie` (SSO) |
+| Jackett | `9117` | indexer aggregator, `jackett.nul.ie` (SSO) |
+| FlareSolverr | — | Cloudflare challenge solver for Jackett |
+| Radarr | `7878` | movies, `radarr.nul.ie` (SSO) |
+| Sonarr | `8989` | TV, `sonarr.nul.ie` (SSO) |
+| Jellyseerr (`seerr`) | `5055` | request portal, `gib.nul.ie` (`openFirewall` on) |
+| PhotoPrism | `2342` | photos, `photos.nul.ie`; password auth, sqlite DB, originals/import under `/mnt/media/photoprism` |
+| copyparty | `3923` | file sharing, `stuff.nul.ie`; serves `/mnt/media/public` (read-only to everyone) and `/priv` → `/mnt/media/stuff` (admin for `dev`), share creation, indexing (`e2dsa`/`e2t`), file-magic checks |
+
+All published through [middleman](middleman.md) as shown. A shared `media` group plus a group-writable
+umask on Radarr/Sonarr gives the apps coordinated access to the media volume.
+
+## Network assignments
+
+See the consolidated [network assignments](../../../../networking.md#box-assignments) table (this box: `jackflix`).
+
+## VPN download path
+
+[`networking.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/jackflix/networking.nix)
+defines a `vpn` WireGuard netdev to **AirVPN NL** using a key and PSK from age secrets:
+
+- Policy routing keeps colony traffic on the main table while everything else falls through to the
+  VPN's dedicated table, so the services stay reachable on the `ctrs` network while outbound
+  torrent traffic exits via AirVPN. `DNSDefaultRoute` is disabled on `host0`; the VPN provides DNS.
+- `transmission` and `jackett` `bindsTo` `systemd-networkd-wait-online@vpn.service` — they only
+  run while the tunnel is up.
+- AirVPN forwards a peer port to Transmission (`peer-port`); the firewall accepts it and drops
+  other new inbound TCP from `vpn`, while non-VPN input is limited to the service ports
+  (netdata, Transmission, Jackett, Radarr, Sonarr, Jellyfin, PhotoPrism) plus copyparty's `3923`
+  from the base config and Jellyseerr's `5055`.
+
+## Storage
+
+Media lives on the shared `/mnt/media` volume (bind-mounted read-write from `shill`); Transmission
+downloads into `/mnt/media/downloads/torrents` with a `.incomplete` directory and configured
+bandwidth and seed-ratio limits.
+
+## Notable config files
+
+- [`nixos/boxes/colony/vms/shill/containers/jackflix/default.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/jackflix/default.nix) — container definition and the media services
+- [`nixos/boxes/colony/vms/shill/containers/jackflix/networking.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/jackflix/networking.nix) — AirVPN WireGuard netdev, policy routing and VPN firewall rules
@@ -0,0 +1,96 @@
+# middleman
+
+The front-end reverse proxy for the colony's public web services — the single ingress that
+`estuary` DNATs HTTP/HTTPS (and Matrix federation on `:8448`) to. Terminates TLS with wildcard
+certificates it issues itself, provides nginx-sso for gated vhosts, and runs a librespeed
+backend.
+
+- **Source:** [`shill/containers/middleman/`](../../../../../nixos/boxes/colony/vms/shill/containers/middleman)
+  (`default.nix`, `vhosts.nix`)
+- **Host:** NixOS container on [`shill`](../README.md) (`my.containers` ephemeral nspawn on the
+  `ctrs` bridge; bind-mounts `/mnt/media` read-only for the static file vhosts)
+- **nixpkgs:** `mine`
+
+## Role
+
+### nginx
+
+The reverse proxy enables `vts`, `fancyindex`, Brotli, kTLS and a proxy cache. Its dynamic resolver
+points at `estuary`, allowing upstreams named under `ams1.int.nul.ie` to resolve again at runtime.
+All vhosts live in
+[`vhosts.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/middleman/vhosts.nix). nginx
+also waits for `colony-psql` through `systemdAwaitPostgres`, avoiding an early-boot DNS stall.
+
+### ACME
+
+`middleman` issues certificates for its own vhosts; it is not a shared CA for other boxes.
+
+- `ams1.int.nul.ie` and its wildcard use a lego `exec` challenge that SSHes to
+  `pdns-file-records@estuary-vm`. This is the default `useACMEHost` certificate internally.
+- `nul.ie`, `*.nul.ie` and `*.s3.nul.ie` use Cloudflare DNS. A `postRun` hook copies renewed
+  material to the `mail` VM and runs `mailcow-ssl-reload` there.
+- Renewal reloads nginx; the `acme` group owns the secret files and includes the nginx user.
+
+### nginx-sso
+
+The `generic` SSO instance at `sso.nul.ie` uses Google OAuth by default and also offers a simple
+username/password provider. Its cookie domain is `.nul.ie`; gated vhosts include the generated
+`server-generic.conf` / `location-generic.conf` snippets from `/etc/nginx/includes/sso/`.
+
+### librespeed
+
+The frontend and backend are published as `speed.nul.ie` and `librespeed.ams1.int.nul.ie`, both
+proxied to `localhost:8989`.
+
+## Network assignments
+
+See the consolidated [network assignments](../../../../networking.md#box-assignments) table (this box: `middleman`).
+
+The firewall allows `http`, `https` and `8448` (Matrix federation). A small nftables SNAT rule
+rewrites outbound IPv6 to the container's own address on `host0`.
+
+## Published vhosts
+
+Everything is under `*.nul.ie` with the public wildcard cert unless noted; defaults applied to
+all vhosts are `onlySSL`, kTLS and HTTP/2. "SSO" = gated behind nginx-sso (`generic` instance).
+
+| Host | Upstream | Notes |
+| --- | --- | --- |
+| `nul.ie` (`_`, default) | static | landing page (`index.html`, CV PDF, SSH pubkey); serves Matrix `.well-known`s and redirects `webfinger`/`nodeinfo`/`host-meta` → `toot.nul.ie`, `atproto-did` → `pds.nul.ie`; `forceSSL` (plain HTTP redirects to HTTPS) |
+| `localhost` | — | loopback-only VTS status page at `/status` (scraped by netdata); plain HTTP |
+| `sso.nul.ie` | `localhost:8082` | nginx-sso endpoint |
+| `netdata-colony.nul.ie` | `<host>.ams1.int.nul.ie:19999` | netdata fan-out over `vm`, `fw`, `ctr`, `oci`, `http`, `jackflix-ctr`, `chatterbox-ctr`, `colony-psql-ctr`; **SSO** |
+| `pass.nul.ie` | `vaultwarden-ctr:8080` | [vaultwarden](vaultwarden.md); `/notifications/hub` proxied with websockets |
+| `matrix.nul.ie` | `chatterbox-ctr:8008` | [chatterbox](chatterbox.md) Synapse client + federation; also listens on `:8448` as federation `default_server`; `= /` redirects to Element; serves Matrix `.well-known`s |
+| `element.nul.ie` | static `element-web` | Element configured for the `nul.ie` homeserver |
+| `torrents.nul.ie` | `jackflix-ctr:9091` | Transmission ([jackflix](jackflix.md)); **SSO** |
+| `jackett.nul.ie` | `jackflix-ctr:9117` | **SSO** |
+| `radarr.nul.ie` | `jackflix-ctr:7878` | **SSO**; websockets |
+| `sonarr.nul.ie` | `jackflix-ctr:8989` | **SSO**; websockets |
+| `gib.nul.ie` | `jackflix-ctr:5055` | Jellyseerr requests |
+| `jackflix.nul.ie` | `jackflix-ctr:8096` | Jellyfin; `/socket` websockets; `/` redirects to `/web/` |
+| `toot.nul.ie` | `toot-ctr:80` | Mastodon — **upstream currently disabled**, see [toot](toot.md) |
+| `pds.nul.ie` | `toot-ctr:3000` | Bluesky PDS ([toot](toot.md)); websockets |
+| `share.nul.ie` | `object-ctr:9090` | Sharry ([object](object.md)); websockets |
+| `stuff.nul.ie` | `jackflix-ctr:3923` | copyparty |
+| `public.nul.ie` (+ alias `p.nul.ie`) | static `/mnt/media/public` | fancyindex file listing; `addSSL` so plain HTTP also works |
+| `mc-map.nul.ie` | `simpcraft-oci:8100` | Minecraft map (OCI container on [`whale2`](../../whale2.md#game-servers)) |
+| `mc-rail.nul.ie` | `simpcraft-oci:3876` | Minecraft railway map ([`whale2`](../../whale2.md#game-servers)) |
+| `mc-map-kink.nul.ie` | `kinkcraft-oci:8100` | Minecraft map ([`whale2`](../../whale2.md#game-servers)) |
+| `speed.nul.ie` | `localhost:8989` | librespeed |
+| `librespeed.ams1.int.nul.ie` | `localhost:8989` | librespeed on the internal domain (internal wildcard cert) |
+| `md.nul.ie` | `object-ctr:3000` | HedgeDoc; websockets |
+| `pb.nul.ie` | `object-ctr:8088` | wastebin |
+| `photos.nul.ie` | `jackflix-ctr:2342` | PhotoPrism; websockets |
+| `pront.nul.ie` | `stream-hi.h.nul.ie:5000` | OctoPrint on the home network ([`stream`](../../../home/stream.md)); `/webcam/` → `:5050`; **SSO** |
+| `hass.nul.ie` | `hass-ctr.h.nul.ie:8123` | [Home Assistant](../../../home/sfh/containers/hass.md) (home network); websockets |
+| `hass-john.nul.ie` | `john-valorant-tun.ams1.int.nul.ie:8123` | remote Home Assistant over the point-to-point tunnel; websockets |
+| `minio.nul.ie` | `object-ctr:9001` | MinIO console; `/ws` websockets |
+| `s3.nul.ie` (+ `*.s3.nul.ie`) | `object-ctr:9000` | MinIO S3 API (virtual-host style via the `*.s3` wildcard cert); `/gitea/packages/` has a hack forcing the correct `Content-Type` for Docker image manifests |
+| `nix-cache.nul.ie` | `object-ctr:5000` | Harmonia Nix binary cache; `.narinfo`/`nar/`/`serve/` paths get immutable `Cache-Control`/`Expires` headers |
+
+## Notable config files
+
+- [`nixos/boxes/colony/vms/shill/containers/middleman/default.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/middleman/default.nix) — container definition: nginx, ACME, nginx-sso, librespeed, secrets
+- [`nixos/boxes/colony/vms/shill/containers/middleman/vhosts.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/middleman/vhosts.nix) — all virtual hosts, the SSO include helpers, and the `.well-known` tree
+- [`nixos/boxes/colony/vms/shill/containers/middleman/default.html`](../../../../../nixos/boxes/colony/vms/shill/containers/middleman/default.html) — default vhost landing page
@@ -0,0 +1,39 @@
+# object
+
+Object storage and the Nix binary cache, plus a few small self-hosted web apps (Sharry,
+HedgeDoc, wastebin).
+
+- **Source:** [`shill/containers/object.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/object.nix)
+- **Host:** NixOS container on [`shill`](../README.md) (bind-mounts `/mnt/minio` and
+  `/mnt/nix-cache` read-write)
+- **nixpkgs:** `mine`
+
+## Role
+
+| Service | Port | Purpose |
+| --- | --- | --- |
+| MinIO | `9000` (S3) / `9001` (console) | S3-compatible object storage, `s3.nul.ie` + `*.s3.nul.ie` (virtual-host style via `MINIO_DOMAIN`), console at `minio.nul.ie`; region `eu-central-1`; data on the `/mnt/minio` XFS volume |
+| Harmonia | `5000` | Nix binary cache at `nix-cache.nul.ie` — `harmonia-dev` cache serves `shill`'s `/nix/store` out of a dedicated store view rooted at `/var/lib/harmonia` (bind-mounted from `/mnt/nix-cache`), signed with the `nix-cache.key` secret; a `harmonia` user with authorized keys exists for cache pushes |
+| Sharry | `9090` | file sharing at `share.nul.ie`; Postgres on [colony-psql](colony-psql.md), files stored in the `share` MinIO bucket; fixed `dev` account + invite signup; mail via `mail.nul.ie`; configured share-size limit |
+| HedgeDoc | `3000` | collaborative markdown notes at `md.nul.ie`; Postgres on [colony-psql](colony-psql.md); anonymous edits but no anonymous notes, email login, no open email registration |
+| wastebin | `8088` | pastebin at `pb.nul.ie` |
+| atticd | `8069` | **currently disabled** (`services.atticd.enable = false`) — an alternative Nix cache that would store locally and sit behind `nix-cache.nul.ie`; config (including the `object/atticd.env` secret) is kept around |
+
+Everything public is fronted by [middleman](middleman.md) (see its vhost table). The
+`minio-client` is installed and the user's `~/.mc/config.json` points at an age-secret config.
+`minio-2025-10-15T17-29-55Z` is allowlisted via `permittedInsecurePackages` (flagged as a TODO).
+
+## Network assignments
+
+See the consolidated [network assignments](../../../../networking.md#box-assignments) table (this box: `object`).
+
+## Backing services
+
+- [colony-psql](colony-psql.md) — Sharry and HedgeDoc databases (atticd too, when enabled).
+- MinIO buckets back other boxes' services: Gitea LFS/packages (with the `middleman` MIME hack
+  for Docker manifests), Mastodon's `mastodon` bucket and the Bluesky PDS `pds` bucket on
+  [toot](toot.md), and Sharry's `share` bucket.
+
+## Notable config files
+
+- [`nixos/boxes/colony/vms/shill/containers/object.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/object.nix) — container definition and all services
@@ -0,0 +1,34 @@
+# qclk
+
+A WireGuard management appliance for the `qclk` network — it terminates the `management`
+tunnel and routes/NATs the `qclk` prefix. No service daemon is currently defined in the config;
+the container provides the network plumbing and opens the API port.
+
+- **Source:** [`shill/containers/qclk/`](../../../../../nixos/boxes/colony/vms/shill/containers/qclk)
+  (`default.nix`)
+- **Host:** NixOS container on [`shill`](../README.md)
+- **nixpkgs:** `mine`
+
+## Role
+
+- **WireGuard `management` interface** — listens on UDP `51821` (`lib.my.c.colony.qclk.wgPort`,
+  allowed through the firewall; `estuary` port-forwards it here) with the private key from the
+  `qclk/wg.key` age secret. Managed devices are static peers, each pinned to its own address in the
+  `qclk` prefix; the peer list currently has a single entry.
+- **Routing/NAT** — `shill` routes the `qclk` prefix to this container, and outbound traffic from
+  `host0` into `management` is
+  SNATed to the container's `qclk` address. Forwarding into `management` is accepted from the
+  AS211024 trusted IPv4 ranges (`lib.my.c.as211024.trusted.v4`).
+- **API port** — TCP `8080` is accepted on the `management` interface (`apiPort`), but note
+  `services = { }`: whatever serves the qclk API is not defined in this configuration today.
+
+## Network assignments
+
+See the consolidated [network assignments](../../../../networking.md#box-assignments) table (this box: `qclk`).
+
+Two assignments: `internal` on the `ctrs` network like the other containers, and `qclk` on the
+`management` WireGuard interface (IPv4 only, no DNS name).
+
+## Notable config files
+
+- [`nixos/boxes/colony/vms/shill/containers/qclk/default.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/qclk/default.nix) — container definition: WireGuard netdev, peer list and firewall rules
@@ -0,0 +1,47 @@
+# toot
+
+Federated-social container. Despite the name, the only service actually running is a **Bluesky
+PDS** — the Mastodon instance ("toots") is **currently disabled**.
+
+- **Source:** [`shill/containers/toot.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/toot.nix)
+- **Host:** NixOS container on [`shill`](../README.md)
+- **nixpkgs:** `mine`
+
+## Role
+
+### Bluesky PDS
+
+The active service listens on port 3000 as `pds.nul.ie`, fronted by [middleman](middleman.md),
+which also redirects `/.well-known/atproto-did` here. It requires invites, applies an upload-size
+limit, and stores blobs in [object](object.md)'s `pds` MinIO bucket. Federation uses the standard
+Bluesky services and crawlers. `toot/pds.env` supplies secrets, including S3 credentials, and mail
+comes from `pds@nul.ie`.
+
+### Mastodon
+
+Mastodon is disabled with `services.mastodon.enable = false`, but its configuration remains:
+
+- `nul.ie` is the local domain and `toot.nul.ie` the web domain.
+- PostgreSQL runs on [colony-psql](colony-psql.md), with local Redis and SMTP through `mail.nul.ie`.
+- Media uses the `mastodon` MinIO bucket, a configured streaming-process pool, and periodic cleanup.
+- [middleman](middleman.md) still proxies the dead vhost and `.well-known` endpoints.
+
+The removed `otpSecretFile` option must be addressed before the service can return.
+
+## Network assignments
+
+See the consolidated [network assignments](../../../../networking.md#box-assignments) table (this box: `toot`).
+
+The firewall allows `http` (the Mastodon nginx vhost) and the PDS port `3000` besides netdata.
+
+## Notes
+
+- The local nginx still carries the Mastodon virtual host (`toot.nul.ie`) with proxy-header
+  overrides for being behind `middleman` — part of the preserved-but-disabled Mastodon setup.
+- `mastodon-init-dirs` appends the S3 secret key to Mastodon's `.secrets_env` (the module has no
+  option for a secret-key file), and `mastodon-init-db` waits for `colony-psql` — moot while
+  Mastodon is disabled.
+
+## Notable config files
+
+- [`nixos/boxes/colony/vms/shill/containers/toot.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/toot.nix) — container definition; active PDS config and the preserved (disabled) Mastodon config
@@ -0,0 +1,33 @@
+# vaultwarden
+
+[Vaultwarden](https://github.com/dani-garcia/vaultwarden), a Bitwarden-compatible password
+manager, published as `pass.nul.ie` through [middleman](middleman.md).
+
+- **Source:** [`shill/containers/vaultwarden.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/vaultwarden.nix)
+- **Host:** NixOS container on [`shill`](../README.md)
+- **nixpkgs:** `mine`
+
+## Role
+
+- **vaultwarden** — HTTP on `[::]:8080`, WebSocket notifications on `3012` (both allowed through
+  the firewall). Web vault enabled, signups disabled, Bitwarden push notifications enabled
+  (`PUSH_ENABLED`). `DOMAIN` is `https://pass.nul.ie`.
+- **SMTP** via `mail.nul.ie:587` (STARTTLS) as `pass@nul.ie`; credentials and other sensitive
+  settings come from the `vaultwarden/config.env` age secret.
+- **Backups** — a `borgbackup` job pushes `/var/lib/vaultwarden` to rsync.net
+  using a repokey-encrypted repository; its passphrase and SSH key come from secrets, and the job
+  keeps daily, weekly and monthly archives according to its configured retention policy.
+
+## Network assignments
+
+See the consolidated [network assignments](../../../../networking.md#box-assignments) table (this box: `vaultwarden`).
+
+## Persistence
+
+`/var/lib/vaultwarden` is persisted through `my.tmproot.persistence` — like the other
+`shill` containers the root is ephemeral and real state lives under `/persist` (bind-mounted
+from the host's `/persist/containers/vaultwarden`).
+
+## Notable config files
+
+- [`nixos/boxes/colony/vms/shill/containers/vaultwarden.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/vaultwarden.nix) — container definition, service config and the borgbackup job
@@ -0,0 +1,34 @@
+# waffletail
+
+The colony Tailscale node: a subnet router and exit node that advertises the colony prefixes
+into the tailnet.
+
+- **Source:** [`shill/containers/waffletail.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/waffletail.nix)
+- **Host:** NixOS container on [`shill`](../README.md)
+- **nixpkgs:** `mine`
+
+## Role
+
+### Tailscale
+
+The node authenticates to `hs.nul.ie` with the secret `tailscale-auth.key`. It disables Tailscale's
+netfilter management, advertises itself as an exit node and advertises the colony IPv4/IPv6 ranges,
+but does not accept routes. UDP port 41641 is open and forwarded here by `estuary`.
+
+### Routing and firewall
+
+`shill` routes the Tailscale prefixes to this container.
+The repository's nftables rules trust `tailscale0`, permit colony-sourced forwarding into the
+tailnet, and SNAT tailnet traffic leaving through `host0` unless its destination is already within
+colony.
+
+## Network assignments
+
+See the consolidated [network assignments](../../../../networking.md#box-assignments) table (this box: `waffletail`).
+
+Two assignments: `internal` on the `ctrs` network like the other containers, and `tailscale` for
+its addresses on the tailnet itself (no DNS name).
+
+## Notable config files
+
+- [`nixos/boxes/colony/vms/shill/containers/waffletail.nix`](../../../../../nixos/boxes/colony/vms/shill/containers/waffletail.nix) — container definition, Tailscale setup and forward/NAT rules
@@ -0,0 +1,80 @@
+# whale2
+
+The colony podman/OCI host, dedicated to game servers (kept off `shill` so
+container churn and resource use stay isolated).
+
+- **Source:** [`nixos/boxes/colony/vms/whale2/`](../../../nixos/boxes/colony/vms/whale2)
+  (`default.nix`, `valheim.nix`, `minecraft/`, `enshrouded.nix`)
+- **Host:** VM on `colony`
+- **nixpkgs:** `mine`
+
+## Role
+
+### Container runtime
+
+OCI containers run under podman (`virtualisation.oci-containers`) with the netavark backend and
+`firewall_driver = "none"`, leaving firewall management to `my.firewall`.
+
+### Routable game servers
+
+Each server gets an address from `extraAssignments` (`valheim-oci`, `simpcraft-oci`, …) on the
+`colony` netavark network. That network is backed by the `oci` interface and `prefixes.oci` v4/v6
+ranges; `lib.my.dockerNetAssignment` supplies the address through `--network=colony:ip=…`.
+`estuary` forwards the public game ports, while IPv6 reaches the containers directly.
+
+### Storage
+
+`/var/lib/containers` is a dedicated XFS disk with project quotas.
+
+## Network assignments
+
+See the consolidated [network assignments](../../networking.md#box-assignments) table (this box: `whale2`).
+
+## Game servers
+
+The OCI containers are documented here (they have no pages of their own).
+Their per-container `extraAssignments` on the `oci` network are listed in the generated
+[network assignments](../../networking.md#box-assignments) table. Ports below are the public ones
+forwarded by `estuary`.
+
+| Container | Ports | Status |
+|---|---|---|
+| `valheim` | `2456-2457`/udp | running |
+| `simpcraft` | `25565` tcp+udp | running |
+| `simpcraft-staging` | `25566` tcp | **disabled** (commented out) |
+| `enshrouded` | `15636-15637`/udp | **disabled** (`enshrouded.nix` not imported) |
+| `kevcraft` | `25567` tcp+udp | running |
+| `kinkcraft` | `25568` tcp+udp | running |
+| `graeme` | `25569` tcp+udp | running |
+
+- **valheim** ([`valheim.nix`](../../../nixos/boxes/colony/vms/whale2/valheim.nix)) —
+  `lloesche/valheim-server`, public server "amogus sus", world `simpland2`,
+  allow-listed Steam IDs, password from agenix.
+- **simpcraft** ([`minecraft/`](../../../nixos/boxes/colony/vms/whale2/minecraft)) —
+  `itzg/minecraft-server` (self-built `git.nul.ie/dev/craftblock` image),
+  Modrinth "Simpcraft" modpack, whitelist + ops.
+- **simpcraft-staging** — the same setup pinned to an older pack version, currently commented out.
+- **kevcraft** — vanilla Minecraft 1.20.1, extra op.
+- **kinkcraft** — same Simpcraft modpack as `simpcraft`.
+- **graeme** — vanilla Minecraft on hard difficulty with its own whitelist.
+- **enshrouded** ([`enshrouded.nix`](../../../nixos/boxes/colony/vms/whale2/enshrouded.nix)) —
+  `sknnr/enshrouded-dedicated-server` ("UWUshrouded"); the file exists but is
+  commented out of `whale2`'s `imports`, so the server is down (its forwards
+  and DNS records remain).
+
+The Minecraft containers share one whitelist/ops list and agenix env file
+(`whale2/simpcraft.env`, which also carries the RCON password).
+
+## Backups
+
+A local borg job (`services.borgbackup.jobs.simpcraft`) archives the `simpcraft` world frequently,
+offset from its autosave timer, into `/var/lib/containers/backup/simpcraft`. It uses `mcrcon` to
+`save-off`/`save-on` around each run and keeps a short history for quick world rollback rather than
+disaster recovery; the `oci` LV itself is covered by `colony`'s `borgthin`.
+
+## Notable config files
+
+- [`nixos/boxes/colony/vms/whale2/default.nix`](../../../nixos/boxes/colony/vms/whale2/default.nix) — VM config, podman/netavark setup, `extraAssignments`.
+- [`nixos/boxes/colony/vms/whale2/valheim.nix`](../../../nixos/boxes/colony/vms/whale2/valheim.nix) — Valheim server.
+- [`nixos/boxes/colony/vms/whale2/minecraft/default.nix`](../../../nixos/boxes/colony/vms/whale2/minecraft/default.nix) — the Minecraft servers + world backup job.
+- [`nixos/boxes/colony/vms/whale2/enshrouded.nix`](../../../nixos/boxes/colony/vms/whale2/enshrouded.nix) — Enshrouded server (disabled, not imported).