# nuclide.systems docs

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

## Read this first
- **[`/CLAUDE.md`](../CLAUDE.md)** (host root) — operator doctrine for any AI agent SSHing in. Skim before touching anything.
- **[`RESUME.md`](RESUME.md)** — open items + recent changes; update at end of every session.
- **[`CHANGELOG.md`](CHANGELOG.md)** — what changed and when.
- **[`ct-inventory.md`](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`](../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](https://ai.nuclide.systems) (Bifrost — LLM + MCP gateway) · [chat.nuclide.systems](https://chat.nuclide.systems) (Open WebUI)
- **Files**: [nc.nuclide.systems](https://nc.nuclide.systems) (Nextcloud) · [paperless.nuclide.systems](https://paperless.nuclide.systems) · [immich.nuclide.systems](https://immich.nuclide.systems)
- **Dev**: [git.nuclide.systems](https://git.nuclide.systems) (Gitea) · [dev.nuclide.systems](https://dev.nuclide.systems) (Coder)
- **Home**: [ha.nuclide.systems](https://ha.nuclide.systems) (Home Assistant) · [hoarder.nuclide.systems](https://hoarder.nuclide.systems) (Karakeep) · [memos.nuclide.systems](https://memos.nuclide.systems)
- **Identity**: [id.nuclide.systems](https://id.nuclide.systems) (Pocket-ID) · [vault.nuclide.systems](https://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](https://git.nuclide.systems/fkrebs/docs) | This doc site | Push after every doc change |
| [fkrebs/homelab-configs](https://git.nuclide.systems/fkrebs/homelab-configs) | Homarr config, Alloy configs, monitoring compose files | Cron 03:00 on CT 109 |
| [fkrebs/n8n-flows](https://git.nuclide.systems/fkrebs/n8n-flows) | n8n workflow JSON exports + ideas backlog (10 issues) | Cron 03:30 on CT 104 |
| [fkrebs/zoraxy-conf](https://git.nuclide.systems/fkrebs/zoraxy-conf) | Zoraxy proxy routes (CT 108) | Cron 03:00 on CT 108 |
| [fkrebs/adguard-conf](https://git.nuclide.systems/fkrebs/adguard-conf) | AdGuard Home config (CT 102) | Cron 03:00 on CT 102 |
| [fkrebs/pve-conf](https://git.nuclide.systems/fkrebs/pve-conf) | Proxmox LXC/VM configs + storage | Cron 03:00 on nuc |
| [fkrebs/ct103-backrest](https://git.nuclide.systems/fkrebs/ct103-backrest) | Backrest config + scripts (CT 103) | Cron 03:15 on nuc |
| [fkrebs/ct104-stacks](https://git.nuclide.systems/fkrebs/ct104-stacks) | CT 104 untracked stack composes (no .env) | Cron 03:15 on nuc |
| [fkrebs/ct110-pocket-id](https://git.nuclide.systems/fkrebs/ct110-pocket-id) | Pocket-ID compose (CT 110) | Cron 03:15 on nuc |
| [fkrebs/ct111-dev](https://git.nuclide.systems/fkrebs/ct111-dev) | Coder templates + act-runner (CT 111) | Cron 03:15 on nuc |
| [fkrebs/ct112-infisical](https://git.nuclide.systems/fkrebs/ct112-infisical) | Infisical compose (CT 112, private) | Cron 03:15 on nuc |
| [fkrebs/unas-conf](https://git.nuclide.systems/fkrebs/unas-conf) | UNAS Pro NFS exports, disk usage, cron (192.168.1.31) | Cron 03:20 on nuc |
| [fkrebs/grafana-dashboards](https://git.nuclide.systems/fkrebs/grafana-dashboards) | Grafana dashboard JSON exports + datasources (CT 109) | Cron 03:25 on CT 109 |
| [fkrebs/ct113-db](https://git.nuclide.systems/fkrebs/ct113-db) | Postgres + pgAdmin compose (CT 113) | Cron 03:15 on nuc |
| [fkrebs/klipper-config](https://git.nuclide.systems/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.