119 lines
6.3 KiB
Markdown
119 lines
6.3 KiB
Markdown
> **STATUS: NARRATIVE — historical writeup. Not authoritative for current state.**
|
||
|
||
---
|
||
|
||
# Case Study — The Nuclide Homelab, built with Claude
|
||
|
||
## Origin story
|
||
|
||
One Saturday, the owner's wife left him home alone. He got bored, subscribed to
|
||
Claude, and started tinkering with a home server. That afternoon of boredom
|
||
turned into the `/opt/stacks` ecosystem documented here — a ~66-container,
|
||
~23-stack self-hosted platform with SSO, an MCP/agent gateway, GPU offload,
|
||
and a fully audited network. This is that story, kept as a record of what a
|
||
curiosity-driven collaboration produced.
|
||
|
||
> This is a personal passion project, not a work deliverable. The tone and
|
||
> scope reflect that: depth and exploration over minimum-viable.
|
||
|
||
## What was built (high level)
|
||
|
||
- **AI/agent core** — LiteLLM model gateway (~28 curated models), an
|
||
MCP gateway that DinD-spawns and OAuth-gates MCP servers, an Agent Operator
|
||
(cron/event agents), semantic tool retrieval, MCP→LobeChat registration.
|
||
- **Identity** — PocketID as the universal OIDC IdP; every service behind SSO
|
||
(LiteLLM, LobeChat, n8n, Nextcloud, Daytona via a Keycloak→PocketID adapter).
|
||
- **Data layer** — shared-postgres standard; a full **tier-1 "no SQLite on
|
||
NFS"** migration (ntfy, Karakeep, Arcane, traccar → local disk; Memos +
|
||
Vaultwarden → Postgres via pgloader); WAL-G PITR backups re-established.
|
||
- **Network** — full read-only UniFi audit + the unmanaged D-Link DGS-1210
|
||
core (SNTP fixed, topology/FDB mapped, DHCP/LLDP interop verified, SPOF
|
||
identified); pinned-NTP-source standard adopted.
|
||
- **Reliability** — gateway **deep health-check** (real MCP tool-call probe,
|
||
usage-aware backoff) that caught silently-broken servers.
|
||
- **Cloud burst** — on-demand Scaleway L40S GPU offload via WireGuard.
|
||
|
||
See `homelab-architecture.md` for the living technical reference and
|
||
`PORTMAP.md` for the authoritative port/route map.
|
||
|
||
## Activity signal
|
||
|
||
- **~79 commits in the trailing 14 days** (`git log --since="14 days ago"`),
|
||
spanning gateway OAuth/health, OIDC bolt-ons, DB migrations, network audit,
|
||
GPU integration, and docs.
|
||
- Multi-session, incident-driven: several entries trace to real failures
|
||
caught and fixed (WAL-G archiver hung silently ~13 h; n8n `latest`-drift
|
||
outage; SQLite-on-NFS corruption risk; an 8.5-month-stale switch clock).
|
||
|
||
## Productivity estimate (honest framing)
|
||
|
||
These are **rough order-of-magnitude estimates**, not measurements. Assumptions
|
||
are stated so they can be challenged.
|
||
|
||
- Scope delivered ≈ a small platform: identity, AI gateway, agent runtime,
|
||
~23 service stacks, a DB-migration program, a full network audit, backups.
|
||
- A solo engineer doing this unaided, part-time, learning the unfamiliar
|
||
pieces (OIDC internals, pgloader, MCP, UniFi/D-Link internals): a
|
||
conservative bound is **several hundred focused hours** (≈ 8–16 part-time
|
||
weeks). Assumes the owner is competent but not a specialist in every domain
|
||
touched (identity, Postgres ops, embedded-switch web UIs, MCP).
|
||
- With the assistant: compressed into a small number of intensive sessions
|
||
over ~2 weeks. The leverage is largest where the work is *research-heavy
|
||
but low-novelty* — reverse-engineering a D-Link form POST, deriving an
|
||
OIDC redirect, mapping an FDB table — i.e. tasks that are tedious solo but
|
||
not conceptually hard. The leverage is smallest on genuine judgment calls
|
||
(what to prioritise, what risk is acceptable), which stayed with the owner.
|
||
- **Caveat:** estimate excludes the owner's own steering/review time, which
|
||
was substantial and is the reason the output is coherent rather than just
|
||
voluminous.
|
||
|
||
## CO2 estimate (honest framing)
|
||
|
||
Also order-of-magnitude, assumptions explicit.
|
||
|
||
- **LLM inference:** a heavy multi-session collaboration of this kind is on
|
||
the order of a few million tokens. Public estimates put frontier-model
|
||
inference at roughly 1–5 Wh per ~1k output tokens equivalent (wide error
|
||
bars). Taking ~3 M tokens × ~2 Wh/1k ≈ **~6 kWh** → at a ~0.35 kgCO2e/kWh
|
||
grid ≈ **~2 kgCO2e**. Plausible range **1–5 kgCO2e**. Datacenter PUE and
|
||
exact model size dominate the uncertainty.
|
||
- **Homelab runtime** (the larger ongoing footprint): the NUC 14 Pro draws
|
||
~15–45 W under mixed load. At ~30 W average → ~0.72 kWh/day → ~260 kWh/yr
|
||
→ **~90 kgCO2e/yr** at the same grid factor. The German grid is cleaner
|
||
than that average in many hours, so treat as an upper-ish bound. The
|
||
on-demand Scaleway L40S burst is deliberately *on-demand* precisely to
|
||
avoid a 24/7 GPU's footprint.
|
||
- **Takeaway:** the assistant-collaboration carbon is a rounding error next
|
||
to a year of always-on homelab power. Efficiency wins (CPU-only default,
|
||
on-demand GPU, idle-aware health probing) matter more than the chat cost.
|
||
|
||
## Handover / current state
|
||
|
||
**Healthy & verified**
|
||
- Tier-1 SQLite-off-NFS: complete.
|
||
- OIDC: n8n (302→PocketID, client `33135ad4`) and LobeChat (`AUTH_TRUSTED_
|
||
ORIGINS` fix, sign-in→PocketID) — both verified; LobeChat wants one real
|
||
browser login as final proof.
|
||
- D-Link SNTP: fixed (pinned PTB+Cloudflare IPs, clock corrected & synced).
|
||
- Gateway deep health-check: live, usage-aware, surfaced in `/api/servers`.
|
||
|
||
**Open / pending** (see `homelab-architecture.md` roadmap for detail)
|
||
- **Broken MCP servers** surfaced by the new health-check: `memos`
|
||
(degraded — `mcp-memos` can't resolve `memos` host; Docker-network
|
||
isolation), `context7`/`crawl4ai`/`markitdown` (down), `nextcloud`
|
||
(probe false-positive — needs `health_check:false` or per-user creds).
|
||
- **D-Link mgmt hardening** (bundle, confirm-first): HTTPS, SNMP review,
|
||
Trusted-Host allowlist `192.168.1.0/24`. Shared `tapirnase` password
|
||
reuse (WiFi/LiteLLM/switch) — rotation deferred, noted.
|
||
- **Network**: IoT-VLAN segmentation; D-Link is the unmanaged core/SPOF;
|
||
mgmt-TLS certs for Proxmox + D-Link.
|
||
- **Platform**: env→secret vault; LobeChat external-feature disable;
|
||
observability LXC; agent-platform evolution (memory/teams/MCP-exposed).
|
||
- `nexa` analysis blocked — private repo; deploy key pending authorization.
|
||
|
||
**Operating rules to preserve**
|
||
- Confirm + risk-assess before any Proxmox / Ubiquiti / network-gear write.
|
||
- Never put DB/SQLite on the UNAS NFS share.
|
||
- Only a full pgloader of *all* tables is a complete DB migration.
|
||
- Prefer self-hosted; pin critical container images (no `latest` drift).
|