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,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