From 08605ab4221e59f695fceafdad3b3ffe64902c50 Mon Sep 17 00:00:00 2001 From: Jack O'Sullivan Date: Sun, 2 Aug 2026 00:23:06 +0100 Subject: [PATCH] docs/boxes: Prioritize hardware details Place physical hardware inventories and VPS resource allocations near the top of each box page, while leaving broader platform details in their topical sections. --- AGENTS.md | 8 +++++--- docs/mobile/tower.md | 22 +++++++++++----------- docs/remote/britnet.md | 16 ++++++++-------- docs/remote/britway.md | 16 ++++++++-------- docs/sites/colony/colony.md | 24 ++++++++++++------------ docs/sites/home/castle.md | 22 +++++++++++----------- docs/sites/home/palace.md | 24 ++++++++++++------------ docs/sites/home/stream.md | 30 ++++++++++++++---------------- 8 files changed, 81 insertions(+), 81 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b061ca5..dcbf607 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -212,10 +212,12 @@ physical box share a name, the site keeps the `README.md` and the box page stays example `sites/colony/README.md` and `sites/colony/colony.md`). **Box page layout** (match the existing pages): H1 + a one-line intro; a short bullet list of -`Source` / `Host` / `nixpkgs`; `## Role`; `## Network assignments` that **links** to +`Source` / `Host` / `nixpkgs`; an optional hardware inventory or VPS resource-allocation section; +`## Role`; `## Network assignments` that **links** to [`networking.md#box-assignments`](docs/networking.md#box-assignments) (never inline the table); one -`##` section per topic; `## Notable config files` last. A box without static assignments still gets -the section with a short explanation instead of a generated-table link. +`##` section per topic; `## Notable config files` last. Keep non-hardware platform details in their +topical sections rather than moving them with the inventory. A box without static assignments still +gets the section with a short explanation instead of a generated-table link. **Structure and layout:** - Use **tables** for lists of structured items (BGP peers, forwarded ports, vhosts, containers, diff --git a/docs/mobile/tower.md b/docs/mobile/tower.md index ac65837..b911581 100644 --- a/docs/mobile/tower.md +++ b/docs/mobile/tower.md @@ -6,17 +6,6 @@ Portable workstation — a Framework Laptop 13 (Intel), running the full GUI env - **Host:** physical (laptop) - **nixpkgs:** `mine` -## Role - -- Personal portable workstation: `my.gui.enable`, with Sway managed by home-manager. -- Joins the tailnet through the headscale on [`britway`](../remote/britway.md) (fish abbr - `tsup` = `doas tailscale up --login-server=https://hs.nul.ie --accept-routes`). - -## Network assignments - -`tower` has no static assignment; it uses DHCP through NetworkManager and reaches the other boxes -over Tailscale. - ## Hardware / platform | Component | Inventory | @@ -32,6 +21,17 @@ The configuration enables Intel microcode updates, `kvm-intel`, `intel_iommu=on` `intel-media-driver` and the latest kernel (`lib.my.c.kernel.latest`). Thunderbolt security (`bolt`), the fingerprint reader (`fprintd`) and `tlp` power management are also enabled. +## Role + +- Personal portable workstation: `my.gui.enable`, with Sway managed by home-manager. +- Joins the tailnet through the headscale on [`britway`](../remote/britway.md) (fish abbr + `tsup` = `doas tailscale up --login-server=https://hs.nul.ie --accept-routes`). + +## Network assignments + +`tower` has no static assignment; it uses DHCP through NetworkManager and reaches the other boxes +over Tailscale. + ## Storage - Two LUKS-encrypted partitions, `persist` and `home` (both `allowDiscards`); `/nix` is a diff --git a/docs/remote/britnet.md b/docs/remote/britnet.md index 87dc200..a45daaf 100644 --- a/docs/remote/britnet.md +++ b/docs/remote/britnet.md @@ -7,6 +7,14 @@ narrower gateway role than [`britway`](britway.md) (no control plane, no BGP). - **Host:** VPS (Birmingham, `bhx1`; provider uplink assignment `allhost`) - **nixpkgs:** `mine` +## Platform + +| Component | Allocation | +|---|---| +| Virtualisation | KVM/QEMU guest | +| Compute | 2 vCPUs and 2 GiB RAM | +| Storage | 32 GiB virtio disk with separate ext4 filesystems for `/boot`, `/nix` and `/persist`; root is tmpfs | + ## Role - **Tailscale exit node** — logs into the headscale on [`britway`](britway.md) @@ -20,14 +28,6 @@ narrower gateway role than [`britway`](britway.md) (no control plane, no BGP). See the consolidated [network assignments](../networking.md#box-assignments) table (this box: `britnet`). -## Platform - -| Component | Allocation | -|---|---| -| Virtualisation | KVM/QEMU guest | -| Compute | 2 vCPUs and 2 GiB RAM | -| Storage | 32 GiB virtio disk with separate ext4 filesystems for `/boot`, `/nix` and `/persist`; root is tmpfs | - ## Networking - The provider interface is renamed to `veth0` by MAC. Its IPv6 default gateway sits off-subnet, so diff --git a/docs/remote/britway.md b/docs/remote/britway.md index f55ffe6..125bf40 100644 --- a/docs/remote/britway.md +++ b/docs/remote/britway.md @@ -7,6 +7,14 @@ control plane, a tailnet exit node, and the BGP speaker for AS211024. - **Host:** VPS at Vultr (London, `lon1`) - **nixpkgs:** `mine` +## Platform + +| Component | Allocation | +|---|---| +| Virtualisation | Vultr VC2 virtual guest on a QEMU-compatible platform | +| Compute | 2 vCPUs and 2 GiB RAM | +| Storage | 65 GiB virtio disk with separate ext4 filesystems for `/boot`, `/nix` and `/persist`; root is tmpfs | + ## Role - **Headscale** — the self-hosted Tailscale control plane at `hs.nul.ie`; every other box's @@ -27,14 +35,6 @@ control plane, a tailnet exit node, and the BGP speaker for AS211024. See the consolidated [network assignments](../networking.md#box-assignments) table (this box: `britway`). -## Platform - -| Component | Allocation | -|---|---| -| Virtualisation | Vultr VC2 virtual guest on a QEMU-compatible platform | -| Compute | 2 vCPUs and 2 GiB RAM | -| Storage | 65 GiB virtio disk with separate ext4 filesystems for `/boot`, `/nix` and `/persist`; root is tmpfs | - ## Networking - Two assignments: `vultr` on the provider interface `veth0` (renamed by MAC), and `as211024` diff --git a/docs/sites/colony/colony.md b/docs/sites/colony/colony.md index 291fe3e..00eb345 100644 --- a/docs/sites/colony/colony.md +++ b/docs/sites/colony/colony.md @@ -8,6 +8,18 @@ everything at the colony site. - **Host:** bare metal (this *is* the physical box) - **nixpkgs:** `mine-stable` +## 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 | + ## Role Bare-metal AMD host. It does little application work itself — its job is to run @@ -55,18 +67,6 @@ Netdata uses FreeIPMI while ignoring the VCCM sensor. The box also runs `smartd` 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 diff --git a/docs/sites/home/castle.md b/docs/sites/home/castle.md index 6e9256f..3dc4557 100644 --- a/docs/sites/home/castle.md +++ b/docs/sites/home/castle.md @@ -7,6 +7,17 @@ root storage on NVMe-oF volumes from `cellar`. - **Host:** physical - **nixpkgs:** `mine` +## Hardware + +| Component | Inventory | +|---|---| +| Platform | ASUS ProArt X670E-CREATOR WIFI | +| CPU | AMD Ryzen 9 7950X (16 cores / 32 threads) | +| Memory | 64 GiB | +| Graphics | Integrated AMD Radeon graphics | +| Network | Mellanox ConnectX-4 100G, Aquantia AQC113CS 10G, Intel I225-V 2.5G and MediaTek MT7922 Wi-Fi 6E controllers | +| System storage | No local root disk; the box netboots and uses the SPDK NVMe-oF namespace exported by `cellar` | + ## Role ### Desktop @@ -38,17 +49,6 @@ a `drm-amd-display` flicker patch remains commented out. See the consolidated [network assignments](../../networking.md#box-assignments) table (this box: `castle`). -## Hardware - -| Component | Inventory | -|---|---| -| Platform | ASUS ProArt X670E-CREATOR WIFI | -| CPU | AMD Ryzen 9 7950X (16 cores / 32 threads) | -| Memory | 64 GiB | -| Graphics | Integrated AMD Radeon graphics | -| Network | Mellanox ConnectX-4 100G, Aquantia AQC113CS 10G, Intel I225-V 2.5G and MediaTek MT7922 Wi-Fi 6E controllers | -| System storage | No local root disk; the box netboots and uses the SPDK NVMe-oF namespace exported by `cellar` | - ## Networking - `et100g` (100G, MTU 9000) carries `lan-hi` (the `hi` assignment, also pinned by a kea diff --git a/docs/sites/home/palace.md b/docs/sites/home/palace.md index 89ffe94..27a671d 100644 --- a/docs/sites/home/palace.md +++ b/docs/sites/home/palace.md @@ -8,18 +8,6 @@ SR-IOV VFs, PCI NVMe drives and LVM disks. - **Host:** physical - **nixpkgs:** `mine-stable` -## Role - -- Home hypervisor: VMs are declared in `my.vms.instances` - ([`palace/vms/default.nix`](../../../nixos/boxes/home/palace/vms/default.nix)); disks are LVs in - the `main` thin pool (`services.lvm.boot.thin.enable`). -- AMD box (`kvm-amd`, `amd_iommu=on`, microcode updates); the kernel is built with - `ACPI_APEI_PCIEAER`/`PCIEAER` for the PCIe passthrough work below. - -## Network assignments - -See the consolidated [network assignments](../../networking.md#box-assignments) table (this box: `palace`). - ## Hardware | Component | Inventory | @@ -32,6 +20,18 @@ See the consolidated [network assignments](../../networking.md#box-assignments) | NVMe storage | Three 2 TB Samsung NVMe devices passed through to `cellar`; SPDK combines them as the `NVMeRaid` RAID 0 device | | Network / graphics | Mellanox ConnectX-4 100G adapter with four SR-IOV VFs, two Intel I211 Gigabit Ethernet controllers, and an AMD Radeon RX 550/560-family GPU | +## Role + +- Home hypervisor: VMs are declared in `my.vms.instances` + ([`palace/vms/default.nix`](../../../nixos/boxes/home/palace/vms/default.nix)); disks are LVs in + the `main` thin pool (`services.lvm.boot.thin.enable`). +- AMD box (`kvm-amd`, `amd_iommu=on`, microcode updates); the kernel is built with + `ACPI_APEI_PCIEAER`/`PCIEAER` for the PCIe passthrough work below. + +## Network assignments + +See the consolidated [network assignments](../../networking.md#box-assignments) table (this box: `palace`). + ## Networking 100G `et100g` (mlx5, MTU 9000) uplinks to the `dave` switch and carries `lan-hi` (VLAN 100, the diff --git a/docs/sites/home/stream.md b/docs/sites/home/stream.md index b15656b..3963a53 100644 --- a/docs/sites/home/stream.md +++ b/docs/sites/home/stream.md @@ -8,6 +8,18 @@ redundant router pair with [`river`](river.md) and is dual-homed to both switche - **Host:** physical - **nixpkgs:** `mine` +## Hardware + +| Component | Inventory | +|---|---| +| Platform | BROUNION R86S | +| CPU | Intel Celeron N5105 (4 cores / 4 threads) | +| Memory | 16 GiB | +| Storage | 512 GB Samsung SSD 970 PRO NVMe containing `/boot`, `/nix` and `/persist`; integrated 128 GB eMMC is present but is not used by the declared filesystems | +| Network | Three Intel `igc` interfaces and a dual-port Mellanox `mlx4_en` adapter; `wan`, `lan-jim` and `lan-dave` use three of these ports | + +The platform configuration enables `kvm-intel`, `intel_iommu=on` and Intel microcode updates. + ## Role At `routing-common` index 1, `stream` normally holds the secondary position in the router pair. @@ -61,28 +73,14 @@ box sets: reaching the modem subnet (needed only because it shares `wan`; WAN egress is otherwise accepted). -## Platform - -### Hardware - -| Component | Inventory | -|---|---| -| Platform | BROUNION R86S | -| CPU | Intel Celeron N5105 (4 cores / 4 threads) | -| Memory | 16 GiB | -| Storage | 512 GB Samsung SSD 970 PRO NVMe containing `/boot`, `/nix` and `/persist`; integrated 128 GB eMMC is present but is not used by the declared filesystems | -| Network | Three Intel `igc` interfaces and a dual-port Mellanox `mlx4_en` adapter; `wan`, `lan-jim` and `lan-dave` use three of these ports | - -The platform configuration enables `kvm-intel`, `intel_iommu=on` and Intel microcode updates. - -### Switching (RSTP) +## Switching (RSTP) `stream` is dual-homed to both switches: `lan-jim` (igc) and `lan-dave` (mlx4_en), both MTU 9000, are enslaved to the `lan` bridge with `STP=true`. [`routing-common/mstpd.nix`](../../../nixos/boxes/home/routing-common/mstpd.nix) runs a patched `mstpd` and forces RSTP on `lan` once it's routable, so exactly one uplink carries traffic at a time. (The remaining NICs are renamed `et2`/`et5` and left unconfigured.) -### Deployment +## Deployment `my.deploy.node.hostname` is currently commented out.