From a7b00e674271811df8d2443c66162993bd17b9a1 Mon Sep 17 00:00:00 2001 From: Fizzlepoof Date: Mon, 25 May 2026 18:02:25 +0000 Subject: [PATCH] docs: capture PD future-state architecture --- docs/README.md | 2 + docs/architecture/ARCHITECTURE_OVERVIEW.md | 11 +- docs/architecture/HARDWARE_INVENTORY.md | 12 + .../pd-future-state-topology.html | 210 +++++++++++++ docs/planning/PD_FUTURE_STATE_ARCHITECTURE.md | 297 ++++++++++++++++++ docs/servers/NOMAD.md | 5 + docs/servers/PLAUSIBLEDENABILITY.md | 11 + docs/servers/ROCINANTE.md | 2 + docs/servers/SERENITY.md | 8 +- 9 files changed, 556 insertions(+), 2 deletions(-) create mode 100644 docs/architecture/pd-future-state-topology.html create mode 100644 docs/planning/PD_FUTURE_STATE_ARCHITECTURE.md diff --git a/docs/README.md b/docs/README.md index ac2c287..639681a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,6 +18,7 @@ Central index for all homelab infrastructure documentation. | [Architecture Overview](architecture/ARCHITECTURE_OVERVIEW.md) | Full stack diagram and service map | | [Services Directory](architecture/SERVICES_DIRECTORY.md) | All services with hosts, ports, and status | | [Networking Model](architecture/NETWORKING_MODEL.md) | VLANs, firewall policy, DHCP DNS, and remote access | +| [PD Future-State Topology](architecture/pd-future-state-topology.html) | Visual target-state diagram for the PD rebuild, cyber VM lane, and Serenity retirement | | [AI Services Network](architecture/AI_SERVICES_NETWORK.md) | Cross-stack Docker networking for AI services | ## Stacks @@ -34,6 +35,7 @@ Central index for all homelab infrastructure documentation. | File | Description | |------|-------------| | [Expansion Plan](planning/HOMELAB_EXPANSION_PLAN.md) | 6-phase buildout — all phases complete as of 2026-05-06 | +| [PD Future-State Architecture](planning/PD_FUTURE_STATE_ARCHITECTURE.md) | Target-state host layout, storage model, cyber VM policy, and Serenity retirement path | | [TODO](planning/TODO.md) | Active and backlog tasks | ## Operations diff --git a/docs/architecture/ARCHITECTURE_OVERVIEW.md b/docs/architecture/ARCHITECTURE_OVERVIEW.md index 69e8e3a..eebcc82 100644 --- a/docs/architecture/ARCHITECTURE_OVERVIEW.md +++ b/docs/architecture/ARCHITECTURE_OVERVIEW.md @@ -1,6 +1,6 @@ # Architecture Overview -Full homelab stack as of 2026-05-09. All 6 expansion phases are complete and deployed. +Current live homelab stack plus the planned direction for the upgraded PD platform. ## Servers @@ -74,3 +74,12 @@ Full homelab stack as of 2026-05-09. All 6 expansion phases are complete and dep 4. **NFS for Immich** — photo library lives on Serenity's large array; PD mounts on demand (not at boot) 5. **TrueNAS manages Docker** — never use `systemctl restart docker` on PD; use `docker compose` or `docker restart` for individual containers 6. **Credential hygiene** — Gitea pushes from PD/NOMAD use internal SSH (`ssh://git@10.5.30.6:2222//.git`); GitHub remote uses SSH key (`/root/.ssh/id_gitea`) + +## Planned Direction — upgraded PD + Serenity retirement + +- **PD stays on bare-metal TrueNAS Scale** and becomes the long-term production center of gravity for storage, Docker, shared databases, media, identity, monitoring, and the primary DNS source node. +- **PD may also host cybersecurity VMs**, but only inside a dedicated lab VLAN / policy lane with default-deny access into production. +- **N.O.M.A.D. remains the trusted secondary lane** for offline knowledge, game hosting, and the backup Technitium resolver. +- **Rocinante becomes optional** if PD receives the 4090; otherwise it stays the heavy inference specialist. +- **Serenity is transitional**: as long as it owns the storage, qBittorrent/ARR locality can remain there; once PD directly owns the storage, that path-locality argument flips and the remaining torrent/media-ingest stack should move to PD before Serenity is retired. +- See [../planning/PD_FUTURE_STATE_ARCHITECTURE.md](../planning/PD_FUTURE_STATE_ARCHITECTURE.md) for the full target-state plan and [pd-future-state-topology.html](pd-future-state-topology.html) for the visual operator map. diff --git a/docs/architecture/HARDWARE_INVENTORY.md b/docs/architecture/HARDWARE_INVENTORY.md index 6ba0e9f..3185f2d 100644 --- a/docs/architecture/HARDWARE_INVENTORY.md +++ b/docs/architecture/HARDWARE_INVENTORY.md @@ -47,6 +47,18 @@ ### NFS Mounts - Serenity data array → `/mnt/unraid/data` +### Planned PD upgrade target +- **Platform:** HL15 Beast ASRock build (`ASRock ROMED8-2T`) +- **Recommended CPU floor:** EPYC 7282 +- **Preferred long-term CPU:** EPYC 7452 if budget allows +- **RAM floor:** 64GB +- **Preferred RAM if hosting production plus multiple cyber VMs:** 128GB +- **PSU guidance:** keep the RM1000x unless a 4090-class GPU is likely; move to HX1500i when the 4090 plan becomes real +- **Planned storage growth:** + - adopt Serenity's storage role into PD + - add a second HDD-backed ZFS pool using 5-6 new 20TB+ drives + - add SSD/NVMe tiers for apps, databases, VM disks, scratch, and model cache + --- ## N.O.M.A.D. (Offline Knowledge + Game Servers) diff --git a/docs/architecture/pd-future-state-topology.html b/docs/architecture/pd-future-state-topology.html new file mode 100644 index 0000000..f7c9146 --- /dev/null +++ b/docs/architecture/pd-future-state-topology.html @@ -0,0 +1,210 @@ + + + + + + PD Future-State Topology + + + + + + +
+
+

PD Future-State Topology

+
+ Target-state operator map for the post-upgrade homelab: PD becomes the primary production platform, NOMAD remains the trusted secondary lane, Rocinante is optional AI specialization, and Serenity is drained then retired after storage adoption. +
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Internet / Remote Edge + Pangolin VPS, public DNS, external access + + + Production / Servers lane + + + + N.O.M.A.D. + Trusted secondary / resilience lane + • Project NOMAD offline stack + • Pelican / Wings / game servers + • Backup Technitium resolver + • Small bounded utility workloads + Second failure domain. Do not turn into a second PD. + + + + PD (upgraded HL15 Beast) + Primary production core on bare-metal TrueNAS Scale + + + Storage + • imported Serenity capacity + • new 20TB+ HDD pool + • SSD/NVMe app + VM tier + + + Apps + DBs + • Docker / compose + • shared Postgres/MariaDB/Redis + • identity / monitoring / media + + + Media + ARR + • qbit/ARR move here after cutover + • path locality follows the disks + • removes Serenity dependency + + + Cyber VM lane + • AD / Windows / Linux labs + • segmented VLAN + • default-deny to production + + + + Rocinante + Optional AI specialist + • Keep if PD does not get the 4090 + • Otherwise overflow / experimental AI + • Must justify its ongoing power + sprawl + Heavy inference can stay separate if desired, but production does not depend on that. + + + + Serenity + Transition-only platform + Now: storage owner, torrent locality, reranker, backup DNS node + Then: drain services, adopt storage into PD, remove dependency + End-state: retire to reduce power draw and operational sprawl + + + + Lab VLAN policy + • Lab -> production: deny by default + • Trusted admin -> lab: explicit allow + • Lab -> DNS/NTP/internet: allow + • Resource-cap VMs to protect production + • Malware / truly sketchy work should still move elsewhere + + + + Operating principles + 1. PD is the production center of gravity + 2. NOMAD stays the trusted secondary lane + 3. Cyber labs can share hardware, not trust + 4. Design around Serenity retirement + +
+ +
+
+

What belongs on PD

+
    +
  • Primary ZFS storage, production Docker, databases, media, identity, monitoring, and DNS source-of-truth
    • +
  • qBittorrent + ARR stack after the storage move, because path locality should follow the disks
    • +
  • AI primary too if the 4090 lands there
    • +
+
+
+

What remains off PD

+
    +
  • NOMAD keeps offline knowledge, game hosting, and backup DNS
    • +
  • Rocinante stays only if heavy inference separation is still useful
    • +
  • High-risk or sketchy cyber work should eventually move to a dedicated lab node
    • +
+
+
+

What this means for Serenity

+
    +
  • Remove obvious service sprawl early
    • +
  • Preserve storage/torrent locality only until PD owns the storage directly
    • +
  • Retire Serenity once its storage and remaining roles are drained
    • +
+
+
+ +
Generated as a repo-owned planning artifact for the PD rebuild, segmentation plan, and Serenity retirement path.
+
+ + \ No newline at end of file diff --git a/docs/planning/PD_FUTURE_STATE_ARCHITECTURE.md b/docs/planning/PD_FUTURE_STATE_ARCHITECTURE.md new file mode 100644 index 0000000..48dbb53 --- /dev/null +++ b/docs/planning/PD_FUTURE_STATE_ARCHITECTURE.md @@ -0,0 +1,297 @@ +# PD Future-State Architecture Plan + +Status: proposed target state for the next major PD rebuild and Serenity retirement. + +## Goal + +Turn PD into the long-term primary homelab platform while keeping enough separation for resilience and cybersecurity lab work. + +This plan assumes: +- PD is rebuilt on the HL15 Beast ASRock platform +- Serenity is temporary and will be retired after its storage is adopted into PD +- John will add a second HDD ZFS pool using 5-6 new 20TB+ drives +- A few SSDs may be added for appdata, databases, scratch, and cache tiers +- Cybersecurity VMs may live on PD, but only inside a tightly segmented lab lane + +## Recommended platform model + +### Keep PD on bare-metal TrueNAS Scale + +Recommended role: +- primary NAS +- primary production Docker/app host +- primary shared database host +- primary media host +- primary identity/control-plane host +- primary DNS source node +- primary AI host if the 4090 lands here +- limited, disciplined VM host for cybersecurity lab work + +Do not treat PD as an unrestricted cyber range. +Production remains the first-class role. + +## Hardware direction + +### Minimum build worth doing +- HL15 Beast ASRock build +- EPYC 7282 +- 64GB RAM +- RM1000x if no 4090 is going in immediately + +### Preferred long-term build +- HL15 Beast ASRock build +- EPYC 7452 +- 128GB RAM preferred if PD will carry production plus multiple security VMs +- HX1500i if PD is likely to receive the 4090 + +### Why the base model is not recommended +The 7252 + 16GB base build is too small for the intended role once PD becomes: +- primary ZFS host +- primary app host +- primary DB host +- future ARR/qbit host after pool migration +- possible AI host +- bounded cybersecurity VM host + +## Storage model + +### HDD pools +PD should end up with at least two major HDD-backed data classes: + +1. Imported Serenity capacity +- absorb the current Serenity storage role +- preserve large media/archive capacity + +2. New HDD ZFS pool +- 5-6 x 20TB+ drives +- use for future bulk media, archives, backup targets, and growth + +Exact vdev shape should be chosen when the final drive count is locked, but the high-level operating model should be: +- one bulk pool for high-capacity household data +- one or more fast SSD-backed tiers for apps, DBs, and VM-heavy workloads + +### SSD / NVMe role split +Use SSD/NVMe for: +- Docker root +- shared PostgreSQL / MariaDB / Redis data +- write-heavy appdata +- VM disks for cyber lab systems +- AI model cache +- transcode/temp/scratch + +Use HDD pools for: +- media libraries +- document archives +- backups +- long-term storage +- lower-IO datasets + +## Host role layout + +### PD = production core +PD should eventually own: +- ZFS/NAS duties +- production Docker stack +- shared databases +- media stack +- household/productivity stack +- Authentik / identity stack +- monitoring/control plane +- primary Technitium node +- ARR/qbit stack after storage cutover +- AI primary if the 4090 lands here +- controlled cyber lab VMs + +### N.O.M.A.D. = secondary trusted platform +Keep NOMAD for: +- offline knowledge / Project NOMAD +- game servers +- backup Technitium resolver +- small bounded utility workloads + +NOMAD should not become a second general-purpose production host. + +### Rocinante = optional AI specialist +If PD gets the 4090: +- Rocinante becomes optional +- can remain an overflow / experimental inference box +- can later be repurposed or retired + +If PD does not get the 4090: +- Rocinante stays the heavy inference box +- PD remains the production/NAS core + +### Serenity = transition-only +Near-term: +- current storage owner +- current torrent locality host +- current reranker host +- backup Technitium node + +End-state: +- storage role moved into PD +- remaining services drained or moved +- host retired + +## Service placement target + +### Keep on PD long-term +Infrastructure / control plane: +- Gitea +- Homepage +- Uptime Kuma +- Gotify +- RackPeek +- Traefik / Pangolin-side internal ingress +- Authentik +- shared PostgreSQL / MariaDB / Redis +- monitoring stack + +Household / productivity: +- Paperless +- Immich +- Karakeep +- n8n +- KitchenOwl +- DoneTick +- Qui + +Media / library: +- Plex +- Tautulli +- Audiobookshelf +- Calibre-Web +- Seerr +- RomM +- GameVault +- Wizarr +- Shelfmark +- Notifiarr + +AI / search: +- LiteLLM +- OpenWebUI +- Qdrant +- SearXNG +- Ollama light tier +- primary heavy inference too if the 4090 lands on PD +- reranker after Serenity is retired + +Torrent/media ingestion after storage cutover: +- qBittorrent +- qbit_manage +- Gluetun +- unpackerr +- Sonarr / Sonarr-anime +- Radarr +- Lidarr +- Readarr / Readarr-epub +- Prowlarr +- Bazarr +- autobrr + +### Keep off PD long-term +NOMAD: +- Project NOMAD stack +- Pelican / Wings / game servers +- backup Technitium resolver + +Optional elsewhere: +- heavy inference on Rocinante if PD does not get the 4090 +- high-risk security experiments on a future dedicated lab node if the school/lab workload outgrows PD-hosted segmented VMs + +## Cybersecurity VM model on PD + +### This is acceptable on PD +- Windows Server / AD lab VMs +- Windows client VMs +- Linux practice VMs +- Wazuh / SIEM learning stack +- Kali or similar coursework boxes +- isolated vulnerable targets for coursework +- patch/test environments + +### This should remain tightly bounded +- scanning labs +- IDS/packet-capture experiments +- exploit practice +- intentionally vulnerable targets + +These may run on PD only when: +- placed on a dedicated lab VLAN +- firewalled from production by default +- resource-limited +- treated as disposable + +### This should ideally not live on PD +- malware detonation +- unknown or sketchy offensive tooling +- random public PoCs with unclear trust +- anything that could meaningfully threaten production storage or family services + +## Network / VLAN recommendation for the lab lane + +Create or preserve a dedicated lab/security lane with these rules: +- separate VLAN / subnet from production lanes +- default-deny from lab to production +- allow only explicit admin paths from trusted management devices +- allow outbound internet as needed for updates/labs +- allow tightly scoped DNS/NTP/logging paths +- keep identity trust boundaries explicit rather than automatic + +Suggested policy posture: +- Lab -> PD production apps: deny by default +- Lab -> shared DNS: allow +- Lab -> internet: allow with logging +- Trusted admin devices -> lab: explicit allow +- Lab -> management interfaces: explicit deny unless specifically required + +## Phased roadmap + +### Phase 1: document and reduce Serenity sprawl now +- document current host roles and future-state design +- classify Serenity services into keep / move / retire +- move low-risk non-storage-tied apps off Serenity first + +### Phase 2: build upgraded PD +- install TrueNAS Scale on the new PD hardware +- stand up SSD tiers for apps/DBs/VMs +- add the new HDD pool +- validate networking, Docker, GPU, and backup posture + +### Phase 3: move production services into the new PD layout +- migrate any remaining general-purpose apps off Serenity +- relocate databases/appdata onto the intended SSD tier +- validate ingress, monitoring, and DNS roles + +### Phase 4: move the storage-dependent torrent/media automation stack +- after the storage move design is finalized, move qbit + ARR locality to PD +- keep path locality on the box that owns the disks +- then remove the old Serenity-locality requirement + +### Phase 5: move or redesign the remaining special cases +- move reranker onto PD if AI core lands there +- redesign backup DNS so Serenity is no longer required +- preserve at least one off-PD Technitium node on NOMAD + +### Phase 6: retire Serenity +- verify pool adoption is complete +- verify services are drained +- confirm backups and DNS redundancy still work +- power down and retire Serenity + +## Architecture principles + +1. PD becomes the production center of gravity. +2. NOMAD stays a separate trusted failure domain. +3. Rocinante is optional and should justify its existence. +4. Serenity should be designed out of the future state. +5. The cybersecurity lab lane can share PD hardware, but not PD trust boundaries. +6. Production stability beats hypervisor sprawl. + +## Immediate implications for current cleanup work + +For the current Serenity Docker review, the guiding rule is: +- remove obvious sprawl from Serenity now +- do not over-optimize the final placement around Serenity permanence +- remember that once PD directly owns the storage, the qbit/ARR locality argument flips to PD diff --git a/docs/servers/NOMAD.md b/docs/servers/NOMAD.md index f29a7c5..c130b06 100644 --- a/docs/servers/NOMAD.md +++ b/docs/servers/NOMAD.md @@ -12,6 +12,11 @@ Offline survival/knowledge server and game server host. - **Motherboard:** ASRock H97M Pro4 - **UPS:** None +## Planned long-term role +- Keep NOMAD intentionally separate from PD's production stack. +- Continue to host Project NOMAD, game services, and the backup Technitium resolver. +- Accept only small bounded helper workloads; do not let it drift into being a second general-purpose production host. + ## Storage | Device | Size | Mount | Purpose | |--------|------|-------|---------| diff --git a/docs/servers/PLAUSIBLEDENABILITY.md b/docs/servers/PLAUSIBLEDENABILITY.md index 8bef2a4..44b2552 100644 --- a/docs/servers/PLAUSIBLEDENABILITY.md +++ b/docs/servers/PLAUSIBLEDENABILITY.md @@ -2,6 +2,8 @@ Primary Docker host running all production workloads. +> Planned direction: this host remains bare-metal TrueNAS Scale and becomes the long-term primary production platform after the HL15 Beast rebuild. See `docs/planning/PD_FUTURE_STATE_ARCHITECTURE.md`. + ## Specs - **OS:** TrueNAS Scale 25.10.2.1 - **CPU:** Ryzen 9 3950X @@ -76,3 +78,12 @@ Current light-tier notes: ## Pending - Add Pangolin resource + DNS for `ai.paccoco.com` - Install fresh editor + +## Planned future role +- Primary NAS after Serenity retirement +- Primary production Docker/app host +- Primary shared database host +- Primary media / automation / identity / monitoring host +- Primary Technitium source node +- Future home of qBittorrent + ARR after storage ownership moves local to PD +- Acceptable host for tightly segmented cybersecurity VMs, but not an unrestricted lab/free-for-all hypervisor diff --git a/docs/servers/ROCINANTE.md b/docs/servers/ROCINANTE.md index 4e05771..64baa8f 100644 --- a/docs/servers/ROCINANTE.md +++ b/docs/servers/ROCINANTE.md @@ -2,6 +2,8 @@ Heavy AI inference server. +> Planned direction: Rocinante becomes optional if the upgraded PD build receives the 4090. If PD does not get the 4090, Rocinante remains the heavy-inference specialist. + ## Hardware | Component | Details | diff --git a/docs/servers/SERENITY.md b/docs/servers/SERENITY.md index c9ef6e8..f2c8159 100644 --- a/docs/servers/SERENITY.md +++ b/docs/servers/SERENITY.md @@ -1,6 +1,6 @@ # Serenity -NAS, media ingestion, and CPU-based AI inference. +Current NAS, media-ingestion, and CPU-based AI helper host. Planned to retire after the upgraded PD build absorbs its storage role. ## Hardware @@ -68,3 +68,9 @@ Serenity hosts the secondary backup Technitium node on `10.5.30.10`. - No GPU; reranker uses CPU-only TEI image - Tailscale active — reachable at `100.94.87.79` from any Tailscale node + +## Planned future role + +- Transitional only; do not design new long-term dependencies around Serenity. +- Near-term it continues to host storage locality, reranker, and the backup Technitium node. +- Once PD directly owns the storage, qBittorrent/ARR locality should move to PD and Serenity should be drained and retired.