fkrebs
143343decf
- Add RESUME.md for cross-session continuity (open items, key state, constraints) - claude-max-bridge: implement /v1/responses (OpenAI Responses API) with previous_response_id chaining via server-side history injection into system prompt. Root cause of "session already in use": CLI leaves JSONL in un-resumable "dequeued" state after each --print run; fix avoids session reuse entirely. Also fixed: assistant content must be array-of-blocks not plain string (silent JS crash otherwise). - LiteLLM: add pass_through_endpoints for /v1/responses → claude-max-bridge - Storage, volumes, architecture docs reconciled (Vaultwarden → local zfs, Pocket-ID backup, WAL-G fix, apps/ decommission, Nextcloud CIFS→NFS) - Add ideas/, proxmox-memory-audit.md, llm-benchmark.md (new docs this session) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
81 lines
4.0 KiB
Markdown
81 lines
4.0 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.
|
|
- **[`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 on CT 104
|
|
│ ├── 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)
|
|
│
|
|
├── 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.
|