docs/README.md

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.
• 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 on CT 104
│   ├── comfyui.md
│   ├── zoraxy.md                 reverse proxy
│   ├── adguard-dns.md            DNS + rewrites
│   ├── cloud-gpu.md              GPU passthrough + future external GPU
│   └── pocket-id.md              [planned] OIDC IdP + client registry
│
├── stacks/                    ← CT 104 docker stacks notes
│   ├── PORTMAP.md             canonical service → port → public hostname registry
│   ├── CLAUDE.md              agent breadcrumbs (CT 104 specific)
│   ├── storage.md             [being rewritten] storage class per service
│   ├── volumes.md             [being rewritten] volume bindings per stack
│   ├── docker-networks.md
│   └── todo.md
│
├── 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

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

• Pocket-ID admin: https://id.nuclide.systems
• Gitea: https://git.nuclide.systems
• Coder: https://dev.nuclide.systems
• Nextcloud: https://nc.nuclide.systems
• MCP gateway: https://mcp.nuclide.systems
• Zoraxy admin: CT 108 (operator-only; always confirm before any change — see [[feedback_zoraxy_confirm]])
• Proxmox PVE: https://192.168.1.20:8006

Repo

After git-init on 2026-05-20, mirrored to Gitea at fkrebs/docs (pending).