78 lines
3.8 KiB
Markdown
78 lines
3.8 KiB
Markdown
# 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.
|
|
- **[`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 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
|
|
│
|
|
└── 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
|
|
- 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 + rendered site
|
|
- Source: `https://git.nuclide.systems/fkrebs/docs`
|
|
- Rendered (LAN-only, no Zoraxy route): `http://192.168.1.42:13080`
|
|
- Build: docs-server container on CT 111 polls Gitea every 5 min; rebuilds with mkdocs Material on every push.
|