Skip to content

# nuclide.systems docs

Single source of truth for the homelab. Git-tracked since 2026-05-20.

## Read this first

- `/CLAUDE.md` (host root) — operator doctrine for any AI agent SSHing in. Skim before touching anything.
- `RESUME.md` — open items + recent changes; update at end of every session.
- `CHANGELOG.md` — what changed and when.
- `ct-inventory.md` — canonical roster of LXCs / VM, IPs, role, sizing.

## Layout

    /docs/
    ├── README.md                  ← you are here
    ├── CHANGELOG.md               ← dated bullets of every infra change
    ├── ct-inventory.md            ← LXC/VM roster (single source of truth)
    │
    ├── infra/                     ← host-level + cross-cutting state
    │   └── proxmox-state.md       ← the 900-line master state doc (sizing, ZFS, NFS, DNS)
    │
    ├── services/                  ← per-service operational docs (current truth)
    │   ├── homelab-architecture.md   topology + design rationale
    │   ├── dev-environment.md        Coder + Gitea on CT 111
    │   ├── mcp-gateway.md            MCP gateway — DECOMMISSIONED 2026-05-26; see mcp-servers.md for Bifrost
    │   ├── comfyui.md
    │   ├── zoraxy.md                 reverse proxy
    │   ├── adguard-dns.md            DNS + rewrites
    │   ├── cloud-gpu.md              GPU passthrough + future external GPU
    │   └── llm-benchmark.md          LiteLLM model TTFT + TPS benchmark
    │
    ├── infra/                     (continued)
    │   ├── portmap.md             canonical service → port → public hostname registry
    │   ├── storage.md             storage class per service (source of truth)
    │   ├── volumes.md             volume bindings per stack
    │   ├── proxmox-memory-audit.md   CT allocations, host budget, ComfyUI memory analysis
    │   └── docker-networks.md
    │
    ├── stacks/                    ← CT 104 agent notes + legacy stack docs
    │   └── CLAUDE.md              agent breadcrumbs (CT 104 specific)
    │
    ├── services/                  (continued)
    │   ├── backrest.md            Backrest backup (CT 103)
    │   ├── secrets-manager.md     Infisical (CT 112)
    │   ├── databases.md           Postgres CT 113 + per-stack DBs
    │   └── doc-ingestion.md       Paperless + Docling
    │
    ├── history/                   ← frozen / archived
    │   ├── traefik-migration.md                  ABANDONED 2026-05-16 (Zoraxy chosen)
    │   ├── traefik-migration-docker-labels.md    ABANDONED 2026-05-16
    │   ├── mcp-gateway-requirements.md           SUPERSEDED by services/mcp-gateway.md
    │   ├── scrubbing-list-2026-05-17.md          snapshot of cleanup pass
    │   └── case-study.md                         narrative writeup
    │
    ├── ideas/
    │   └── stack-ideas.md
    │
    └── security/                  ← audits + leak analyses
        ├── data-leak-audit-comparison.md
        ├── data-leak-audit-2026-05-20-tr004-cloud-sandbox.md
        ├── data-leak-audit-2026-05-21-tr004-artifacts.md
        └── audit-claude-code-meta.md          self-audit of the Claude Code session that produced these

## Operating principles

See `/CLAUDE.md` for the full doctrine. Highlights: 1. Keep services running; surface synergies and gaps. 2. Enforce consistency: Pocket-ID OIDC, Zoraxy + ACME, `<svc>.nuclide.systems`, secrets in `.env`. 3. Plan rollback at medium+ risk (ZFS snapshots, fresh experimental CTs). 4. Every service should be AI-accessible (MCP / Coder workspace CLI / documented API). 5. Test end-to-end before declaring done. 6. Generate slash commands for recurring maintenance.

## Quick links

### Monitoring (CT 109 · 192.168.1.8)

Service | URL | Notes
--- | --- | ---
Homarr | `http://192.168.1.8:7575` | Service dashboard — start here
Grafana | `http://192.168.1.8:3000` | Dashboards (admin/tapirnase)
Prometheus | `http://192.168.1.8:9090` | Metrics — 90d retention
Loki | `http://192.168.1.8:3100` | Logs — 30d retention, 13 hosts
Alloy UI | `http://192.168.1.8:12345` | Log agent pipeline inspector

### Public services (`*.nuclide.systems`)

- AI: ai.nuclide.systems (Bifrost — LLM + MCP gateway) · chat.nuclide.systems (Open WebUI)
- Files: nc.nuclide.systems (Nextcloud) · paperless.nuclide.systems · immich.nuclide.systems
- Dev: git.nuclide.systems (Gitea) · dev.nuclide.systems (Coder)
- Home: ha.nuclide.systems (Home Assistant) · hoarder.nuclide.systems (Karakeep) · memos.nuclide.systems
- Identity: id.nuclide.systems (Pocket-ID) · vault.nuclide.systems (Vaultwarden)

### Operator-only (LAN)

- Proxmox PVE: `https://192.168.1.20:8006`
- Zoraxy admin: `http://192.168.1.4:8000` (always confirm before any change)
- AdGuard: `http://192.168.1.2` · Backrest: `http://192.168.1.3:9898` · Infisical: `http://192.168.1.7:8200`

## Related repos

Repo | Content | Auto-sync
--- | --- | ---
fkrebs/docs | This doc site | Push after every doc change
fkrebs/homelab-configs | Homarr config, Alloy configs, monitoring compose files | Cron 03:00 on CT 109
fkrebs/n8n-flows | n8n workflow JSON exports + ideas backlog (10 issues) | Cron 03:30 on CT 104
fkrebs/zoraxy-conf | Zoraxy proxy routes (CT 108) | Cron 03:00 on CT 108
fkrebs/adguard-conf | AdGuard Home config (CT 102) | Cron 03:00 on CT 102
fkrebs/pve-conf | Proxmox LXC/VM configs + storage | Cron 03:00 on nuc
fkrebs/ct103-backrest | Backrest config + scripts (CT 103) | Cron 03:15 on nuc
fkrebs/ct104-stacks | CT 104 untracked stack composes (no .env) | Cron 03:15 on nuc
fkrebs/ct110-pocket-id | Pocket-ID compose (CT 110) | Cron 03:15 on nuc
fkrebs/ct111-dev | Coder templates + act-runner (CT 111) | Cron 03:15 on nuc
fkrebs/ct112-infisical | Infisical compose (CT 112, private) | Cron 03:15 on nuc
fkrebs/unas-conf | UNAS Pro NFS exports, disk usage, cron (192.168.1.31) | Cron 03:20 on nuc
fkrebs/grafana-dashboards | Grafana dashboard JSON exports + datasources (CT 109) | Cron 03:25 on CT 109
fkrebs/ct113-db | Postgres + pgAdmin compose (CT 113) | Cron 03:15 on nuc
fkrebs/klipper-config | Klipper 3D printer config | Daily cron from QNAP

## Rendered docs site

- Source: `https://git.nuclide.systems/fkrebs/docs`
- Rendered (LAN-only): `http://192.168.1.8:13080`
- Build: docs-server on CT 109 polls Gitea every 5 min; rebuilds with mkdocs Material on push.