jackos1998
d51f2d62b6
Add a top-level README mapping the boxes and a full docs/ tree: topic pages (architecture, networking, deployment), per-site box pages for colony and home with containers nested under their hosts, remote and mobile boxes, the installer, and the home switch fabric reference (folded in from home-switches.md, with AGENTS.md and code comments retargeted to its new home). Box pages carry marked assignment tables that CI regenerates from nixos.allAssignments. AGENTS.md points at the new docs and keeps its terse agent version of the mechanics, referring to the topic pages for depth.
97 lines
4.7 KiB
Markdown
97 lines
4.7 KiB
Markdown
# Deployment documentation
|
|
|
|
> **Note:** these pages are a work in progress and were **agent-generated** from the repository.
|
|
> They may be incomplete or out of date — treat the Nix configuration as the source of truth.
|
|
|
|
This directory documents the boxes managed by this flake: their roles, network assignments,
|
|
hierarchy, and the services they run. For the mechanics of the repo itself (conventions, module
|
|
system internals for contributors, agent guidance), see [`AGENTS.md`](../AGENTS.md).
|
|
|
|
The two big sites follow the pattern:
|
|
|
|
```
|
|
physical host (VM host)
|
|
└── VM (for things impractical to containerise)
|
|
└── container host VM
|
|
└── NixOS containers (one per application group)
|
|
```
|
|
|
|
Not every box fits this pattern, but **colony** and **home** are organised this way.
|
|
|
|
## Cross-cutting topics
|
|
|
|
- [`architecture.md`](architecture.md) — the custom module system, `my.*` namespace, multiple
|
|
nixpkgs channels, shared module inventory.
|
|
- [`networking.md`](networking.md) — network assignments, domains, site topologies, router HA,
|
|
the AS211024 L2 mesh, BGP, WireGuard, Tailscale.
|
|
- [`deployment.md`](deployment.md) — deploy-rs, devshell commands, secrets workflow, CI.
|
|
|
|
## Site: colony (Amsterdam)
|
|
|
|
Physical host and public-infrastructure hub — see [`sites/colony/README.md`](sites/colony/README.md).
|
|
|
|
```
|
|
colony (physical VM host, ams1)
|
|
├── estuary ── edge router: WAN, firewall/NAT, DNS, BGP (AS211024), WireGuard
|
|
├── shill ──── NixOS container host ──┬── middleman (reverse proxy, ACME, nginx-sso, librespeed)
|
|
│ ├── vaultwarden (password manager)
|
|
│ ├── colony-psql (shared PostgreSQL)
|
|
│ ├── chatterbox (Matrix Synapse + bridges)
|
|
│ ├── jackflix (media stack)
|
|
│ ├── object (MinIO, Harmonia Nix cache, Sharry, HedgeDoc, wastebin)
|
|
│ ├── toot (Bluesky PDS; Mastodon disabled)
|
|
│ ├── waffletail (Tailscale subnet router / exit node)
|
|
│ ├── qclk (WireGuard management appliance)
|
|
│ ├── gam (Terraria server)
|
|
│ └── jam (raw nspawn customer container)
|
|
├── whale2 ─── podman/OCI host for game servers
|
|
├── git ────── Gitea + Gitea Actions runner
|
|
├── mail ───── Debian VM running mailcow (not NixOS)
|
|
└── darts ──── third-party/customer VM (opaque, not NixOS)
|
|
```
|
|
|
|
## Site: home
|
|
|
|
Redundant routers, VM host, storage, IoT containers and the workstation — see
|
|
[`sites/home/README.md`](sites/home/README.md). The hand-configured switch fabric (jim/dave/brian)
|
|
and the Digiweb WAN path are documented in [`sites/home/switches.md`](sites/home/switches.md).
|
|
|
|
```
|
|
h.nul.ie
|
|
├── palace (physical VM host — AMD, 100G, SR-IOV)
|
|
│ ├── river ── primary router VM (PPPoE / Digiweb WAN)
|
|
│ ├── cellar ─ NVMe-oF / SPDK storage target VM
|
|
│ └── sfh ──── container host VM ("services for home")
|
|
│ ├── hass ── Home Assistant + Frigate + MQTT (container)
|
|
│ └── unifi ─ UniFi controller (container)
|
|
├── stream (physical secondary router — Virgin Media WAN)
|
|
└── castle (workstation / gaming desktop — netboot, NVMe-oF root)
|
|
```
|
|
|
|
## Remote boxes
|
|
|
|
Edge VPSes and the remote `kelder` site — see [`remote/README.md`](remote/README.md).
|
|
|
|
- [`remote/britway.md`](remote/britway.md) — London VPS: headscale control plane, Tailscale exit
|
|
node, BGP edge.
|
|
- [`remote/britnet.md`](remote/britnet.md) — Birmingham VPS: Tailscale exit node, WireGuard hub.
|
|
- [`remote/kelder.md`](remote/kelder.md) — secondary home server: container host, Nextcloud,
|
|
Samba, WireGuard to `estuary`.
|
|
- [`remote/kelder-acquisition.md`](remote/kelder-acquisition.md) — media acquisition container.
|
|
- [`remote/kelder-spoder.md`](remote/kelder-spoder.md) — Nextcloud + nginx container.
|
|
|
|
## Mobile boxes
|
|
|
|
- [`mobile/tower.md`](mobile/tower.md) — laptop workstation.
|
|
|
|
## Misc
|
|
|
|
- [`misc/installer.md`](misc/installer.md) — the custom NixOS installer image.
|
|
|
|
## A note on the assignment tables
|
|
|
|
The "Network assignments" tables in box pages (between `<!-- assignments: … -->` markers) are
|
|
**generated from the flake** (`nixos.allAssignments`) by `nix run .#update-docs-assignments` —
|
|
CI refreshes them on push. Hand-written prose and the table's Notes column are preserved; don't
|
|
hand-edit the other cells.
|