fkrebs/docs
1
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add CHANGELOG, ct-inventory, rewrite README as TOC

Browse Source
This commit is contained in:
Florian Krebs
2026-05-20 23:45:51 +02:00
parent 99f93b585f
commit caf133f4a7
3 changed files with 129 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+47
View File
@@ -0,0 +1,47 @@
# Changelog
All notable infrastructure / service / doc changes. Newest first.
## 2026-05-20
### Auth / Identity (single sign-on lockdown)
- **Pocket-ID migrated CT 104 → CT 110 "id"** (`192.168.1.5:11000`). Authoritative writes now on CT 110; old data dir on CT 104 is a stale snapshot. Compose on CT 104 renamed `.MIGRATED-TO-CT110-2026-05-20`. Zoraxy upstream for `id.nuclide.systems` flipped.
- **Pocket-ID 2.7.0 uses bcrypt for OIDC client secrets** — previously some clients (Gitea, Coder) had raw 64-char SHA-256 hex in `oidc_clients.secret`, which silently failed every token exchange. Regenerated both with proper bcrypt hashes; audit also surfaced an orphaned Daytona client and the empty-secret `vscode` row.
- **Gitea SSO via Pocket-ID** wired with bcrypt fix + correct `Scopes` (`openid,profile,email`) + `two_factor_policy=skip` + `ACCOUNT_LINKING=auto` + `ENABLE_AUTO_REGISTRATION=true` + `USERNAME=preferred_username`. Local password sign-in form disabled (`GITEA__service__ENABLE_PASSWORD_SIGNIN_FORM=false`); legacy OpenID 2.0 button hidden (`GITEA__openid__ENABLE_OPENID_SIGNIN=false`).
- **Coder SSO via Pocket-ID** wired. User row flipped `login_type=password → oidc`. `CODER_DISABLE_PASSWORD_AUTH=true` + `CODER_OAUTH2_GITHUB_DEFAULT_PROVIDER_ENABLE=false`. Workspace-side GitHub external_auth left on (for repo cloning).
### Dev environment (new CT 111 "dev", `192.168.1.42`)
- New LXC stood up with Coder + Gitea + their Postgres companions.
- Templates pushed to Coder: **`python-uv`** (persistent, GPU, code-server, baked LiteLLM + Anthropic env, Claude Code auto-install) and **`mcp-sandbox`** (ephemeral, sci stack pre-baked).
- GPU passthrough confirmed: `/dev/dri/by-path/pci-0000:00:02.0-render` exposed; CT 111-level symlink at `/dev/dri/renderD128` (systemd-tmpfiles) so the Docker provider's path parser is happy.
- `dotfiles` repo created at `fkrebs/dotfiles` on Gitea — oh-my-zsh, LiteLLM model picker (`models.env`), docker alias set, `~/.claude/settings.json` permissions allowlist, global Python `CLAUDE.md`, `.gitignore_global`, VSCodium settings + extensions.txt.
- `mkproj` helper appends `[tool.coder]` workspace+owner block to new `pyproject.toml`, copies pre-commit config + `.gitignore`, installs dev deps, initial commit.
### Reverse proxy
- **Zoraxy WebSocket forwarding enabled** for `dev.`, `git.`, `mcp.nuclide.systems` (`EnableWebsocketCustomHeaders=true` + `HeaderRewriteRules.DisableHopByHopHeaderRemoval=true`). Coder agent / Gitea live updates / streamable-MCP all need this. Backups at `/tmp/zoraxy-backup-2026-05-20/` on CT 108.
### MCP gateway
- **`daytona` removed**, **`coder` added** in `/opt/stacks/ai/mcp-gateway/config.json`. The `morning-briefing` scheduled agent's server list updated. Built a small `coder-mcp` image (multi-stage from `ghcr.io/coder/coder:latest` + `uv:bookworm-slim` + `uv tool install mcp-proxy`) that `coder login`s once then runs `coder exp mcp server` behind streamable-HTTP.
- Coder MCP exposes tools `coder_create_task` + workspace lifecycle from `Coder Agent v1.27.1`.
### Decommissions
- **Daytona** (`/opt/stacks/daytona/` + `/opt/stacks/ai/daytona-mcp.yml` on CT 104) — containers stopped + removed; compose files renamed `.DECOMMISSIONED-2026-05-20`. Coder replaces it.
### Docs / governance
- **`/CLAUDE.md` created on host** — operator doctrine for any agent SSHing in: keep things running, enforce consistency, plan rollback at medium-risk+, services AI-accessible by default, test before declaring done, generate slash commands for recurring tasks, inventory skills/commands/MCPs at session start.
- **`/docs` is now a git repo**, baseline at `04d54ac`.
- **Doc reorg** into `infra/ services/ history/ ideas/`. Traefik guides moved to `history/` (Zoraxy is permanent). `mcp-gateway-requirements.md` and `scrubbing-list-2026-05-17.md` also archived.
## 2026-05-19
- **Garage moved off NFS-on-UNAS to local zfs** on CT 104 (`/opt/stacks/shared-db/garage/{meta,data}`) after a WAL-G outage. Tier-1 (SQLite) databases off NFS as a follow-up; UNAS reserved for bulk media + workspace home dirs.
- **n8n reverted to local SQLite** after a Postgres migration attempt failed.
## 2026-05-17
- MCP gateway design frozen. Implementation in `services/mcp-gateway.md`; design rationale archived as `history/mcp-gateway-requirements.md`.
- Per-stack scrubbing pass (see `history/scrubbing-list-2026-05-17.md` for the inventory at that snapshot).
## 2026-05-16
- **Traefik abandoned**, **Zoraxy is the production reverse proxy**. Two migration guides preserved in `history/` for context only.
README.md
+62 -78
View File
@@ -1,85 +1,69 @@
# nuclide.systems — Infrastructure Docs
# nuclide.systems docs
Central documentation for the `nuc` Proxmox homelab and all hosted services.
**Source of truth:** `/docs/` on the Proxmox host (`192.168.1.20`).
This directory is the entry point — docs generated anywhere else should land here.
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.
## Infrastructure
## Layout
| File | Contents |
|------|----------|
| [proxmox-optimizations.md](proxmox-optimizations.md) | Full audit, sizing decisions, action log, pending tasks |
```
/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`](../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.
## Docker Stacks (CT 104 / 192.168.1.40)
## 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`
### Service docs (`stacks/docs/`)
| File | Contents |
|------|----------|
| [homelab-architecture.md](stacks/docs/homelab-architecture.md) | Overall architecture overview |
| [mcp-gateway.md](stacks/docs/mcp-gateway.md) | MCP gateway design and endpoints |
| [mcp-gateway-requirements.md](stacks/docs/mcp-gateway-requirements.md) | MCP gateway requirements |
| [zoraxy-setup.md](stacks/docs/zoraxy-setup.md) | Zoraxy reverse proxy setup notes |
| [AdGuard-DNS-writes.md](stacks/docs/AdGuard-DNS-writes.md) | AdGuard DNS rewrite rules |
| [comfyui-mcp.md](stacks/docs/comfyui-mcp.md) | ComfyUI MCP integration |
| [dev-environment.md](stacks/docs/dev-environment.md) | CT 111 Coder + Gitea dev platform |
| [traefik-migration.md](stacks/docs/traefik-migration.md) | Traefik → Zoraxy migration notes |
| [traefik-migration-docker-labels.md](stacks/docs/traefik-migration-docker-labels.md) | Label mapping reference |
| [cloud-gpu-extension.md](stacks/docs/cloud-gpu-extension.md) | Cloud GPU burst setup |
| [scrubbing-list.md](stacks/docs/scrubbing-list.md) | Services to clean up / decommission |
| [stack-ideas.md](stacks/docs/stack-ideas.md) | Backlog of stack ideas |
| [case-study.md](stacks/docs/case-study.md) | Case study writeup |
### Operational (`stacks/`)
| File | Contents |
|------|----------|
| [PORTMAP.md](stacks/PORTMAP.md) | Port assignments for all services |
| [storage.md](stacks/storage.md) | Volume and storage layout |
| [volumes.md](stacks/volumes.md) | Docker volume inventory |
| [docker-networks.md](stacks/docker-networks.md) | Docker network topology |
| [todo.md](stacks/todo.md) | Outstanding stack tasks |
| [CLAUDE.md](stacks/CLAUDE.md) | Agent breadcrumbs (migrated stacks, dormant services) |
---
## Nexa Project (`stacks/nexa/`)
| File | Contents |
|------|----------|
| [README.md](stacks/nexa/README.md) | Project overview |
| [docs/01-vision-and-scope.md](stacks/nexa/docs/01-vision-and-scope.md) | Vision and scope |
| [docs/02-roadmap.md](stacks/nexa/docs/02-roadmap.md) | Roadmap |
| [docs/03-architecture.md](stacks/nexa/docs/03-architecture.md) | Architecture |
| [docs/04-integration-matrix.md](stacks/nexa/docs/04-integration-matrix.md) | Integration matrix |
| [docs/05-command-system.md](stacks/nexa/docs/05-command-system.md) | Command system |
| [docs/06-classification-logic.md](stacks/nexa/docs/06-classification-logic.md) | Classification logic |
| [docs/07-workflow-spec.md](stacks/nexa/docs/07-workflow-spec.md) | Workflow spec |
| [docs/08-graphrag-architecture.md](stacks/nexa/docs/08-graphrag-architecture.md) | GraphRAG architecture |
| [docs/09-deployment.md](stacks/nexa/docs/09-deployment.md) | Deployment |
| [docs/10-operations.md](stacks/nexa/docs/10-operations.md) | Operations |
| [docs/11-open-questions.md](stacks/nexa/docs/11-open-questions.md) | Open questions |
| [docs/12-optimization-opportunities.md](stacks/nexa/docs/12-optimization-opportunities.md) | Optimization opportunities |
| [docs/13-information-wishlist.md](stacks/nexa/docs/13-information-wishlist.md) | Information wishlist |
---
## AI Agents (`stacks/ai/`)
| File | Contents |
|------|----------|
| [home-info.md](stacks/ai/home-info.md) | Home context for agents |
| [morning-briefing-agent.md](stacks/ai/morning-briefing-agent.md) | Morning briefing agent config |
| [PROMPTING-2026.md](stacks/ai/PROMPTING-2026.md) | Prompting guide 2026 |
---
## Contributing
- Drop new docs in the appropriate subdirectory
- Update this README when adding a new section
- When CT 109 (management LXC) is built, the docs platform will serve this directory
## Repo
After git-init on 2026-05-20, mirrored to Gitea at `fkrebs/docs` (pending).
ct-inventory.md
+20
View File
@@ -0,0 +1,20 @@
# CT / VM inventory
Verified 2026-05-20 via `pct list`, `pct config <id>`, `qm config 100` on `nuc`.
| VMID | Name | Type | IP | Cores | RAM (MiB) | Rootfs | Role | UNAS mount | GPU | Status |
|---|---|---|---|---|---|---|---|---|---|---|
| 100 | haos | VM (q35/OVMF) | DHCP via vmbr0 (`.60`) | 4 | 16384 (balloon 4096) | 32 GiB local-zfs | Home Assistant OS; USB Zigbee dongle (10c4:ea60) passed through | — | no | running |
| 101 | shepard | LXC unpriv | 192.168.1.49/24 | 12 | 32768 | 100 GiB | Shepard product stack (Caddy, frontend, backend, Keycloak, Mongo, Neo4j, TimescaleDB) | mp0 NFS | Intel iGPU (card+render) | running |
| 102 | dns | LXC unpriv | 192.168.1.2/24 | 2 | 1024 | 4 GiB | **AdGuard Home** — LAN DNS resolver + filter | — | no | running |
| 103 | backrest | LXC unpriv | 192.168.1.3/24 | 1 | 512 | 8 GiB | **Backrest** (restic) backup scheduler | mp0 NFS | no | running |
| 104 | docker | LXC unpriv (idmapped) | 192.168.1.40/24 | 16 | 49152 | 200 GiB | Main Docker host — AI/ML + media + identity-adjacent (~65 containers) | mp0 NFS | Intel iGPU (card+render) | running |
| 105 | nextcloud | LXC priv | 192.168.1.41/24 | 4 | 8196 | 100 GiB | Nextcloud AIO | mp0 **CIFS** (`//192.168.1.31/storage`) | Intel iGPU (render only) | running |
| 108 | zoraxy | LXC unpriv | 192.168.1.4/24 | 2 | 2048 | 6 GiB | **Zoraxy** reverse proxy + ACME (`*.nuclide.systems`) | — | no | running |
| 109 | observe | LXC | 192.168.1.6/24 | 4 | 6144 | 30 GiB | **Planned** — Prometheus, Grafana, Arcane Manager, Dozzle, Homarr, Diun, Tinyauth, socket-proxy | — | no | **planned** (see `infra/proxmox-state.md` §16) |
| 110 | id | LXC unpriv | 192.168.1.5/24 | 1 | 1024 | 4 GiB | **Pocket-ID** OIDC IdP (`id.nuclide.systems`); migrated off CT 104 on 2026-05-20 | — | no | running |
| 111 | dev | LXC unpriv | 192.168.1.42/24 | 12 | 32768 | 60 GiB | Dev host — **Coder + Gitea** + workspaces | mp0 NFS | Intel iGPU (render only; symlinked at `/dev/dri/renderD128`) | running |
UNAS NFS = `192.168.1.31:/var/nfs/shared/storage` over NFSv3. CT 105 (Nextcloud) is the lone outlier — it mounts the same UNAS share over **CIFS/SMB 3.1.1**, not NFS.
CT 113 ("db") is mentioned in memory notes (`postgres-consolidation`) as a future consolidation target. Not yet planned in any source-of-truth doc.