diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..7a0dd56 --- /dev/null +++ b/CHANGELOG.md @@ -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. diff --git a/README.md b/README.md index 0d8d37b..4b56196 100644 --- a/README.md +++ b/README.md @@ -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, `.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). diff --git a/ct-inventory.md b/ct-inventory.md new file mode 100644 index 0000000..4a499de --- /dev/null +++ b/ct-inventory.md @@ -0,0 +1,20 @@ +# CT / VM inventory + +Verified 2026-05-20 via `pct list`, `pct config `, `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.