fkrebs
96df6e7bd0
- docs-server now runs on ops (192.168.1.8:13080), not dev (192.168.1.42) - mkdocs.yml: fix site_url (was pointing at .111 instead of .42, now .8) - mkdocs.yml: add all services added since last nav update (pocket-id, backrest, databases, arcane, mcp-servers, llm-benchmark, RESUME, connection-hosts) - portmap.md: move :13080 entry from CT 111 to CT 109 section; add Homarr :7575; fix stale Promtail note → Alloy add-on - README.md: update rendered docs URL to 192.168.1.8:13080 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
108 lines
5.9 KiB
Markdown
108 lines
5.9 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)
|
|
│
|
|
├── 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) (LiteLLM) · [chat.nuclide.systems](https://chat.nuclide.systems) (LobeHub) · [mcp.nuclide.systems](https://mcp.nuclide.systems) (MCP Gateway)
|
|
- **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, service compose files | Cron 03:00 on CT 109 |
|
|
| [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.
|