fkrebs/nexa
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
250a5cb2a6d3e452586a26197f588196a6e30177
nexa/CLAUDE.md
T
Claude 250a5cb2a6 Pin homelab-wide UNAS storage convention; add Phase 6 + info wishlist 
- UNAS layout decoded from the user's tree: services/<svc>/ is the
  homelab-wide docker config store (every container follows the same
  pattern — immich, karakeep, nextcloud, ntfy, paperless-ai, pocketid,
  shelfmark, stremio, traccar, vaultwarden, gluetun). Nexa MUST follow
  the same pattern at services/nexa/. backup/<svc>/ for snapshots.
  Pinned in CLAUDE.md and docs/12 #31.
- Stale services flagged for retirement: services/siyuan/ (migrated to
  Obsidian) and services/open-webui/ (unused, only LobeHub is alive).
  Drops the "two LLM UIs" item (#15) — it's now "retire open-webui".
- Hard-blocklist for any Nexa indexer pinned in CLAUDE.md:
  _sortMe/wallet/**, *.gpg/asc/key/pem/kdbx/credentials/secret, plus
  the Nextcloud appdata dir.
- Three new "future user-facing wins" surfaced from the tree:
  Paperless-AI as a Phase-2.x triage helper for _sortMe/Downloads/,
  media/Recipes/ (~300 entries) as the showcase RAG corpus, and
  Paperless-AI's existing ChromaDB as a potential read-from source
  rather than re-embedding scanned docs.
- Housekeeping campaign in docs/12 §35-37: consolidate postgres,
  audit UNAS-everywhere, S3 archive tier on s3.nuclide.systems.
- Phase 6 added to the roadmap: "Nexa as homelab steward". Polls
  Dockge/docker/Proxmox, diffs vs documented state, emits a daily
  drift report. Most of the housekeeping campaign becomes
  semi-automatic once 6.1-6.3 ship.
- New docs/13-information-wishlist.md packages the still-needed
  inventory as 5-6 paste-and-run tasks, each with explicit "📍 Where"
  markers (which shell or which UI) and what it unblocks. Highest
  leverage = Task 1 (read an existing compose stack to lock Q19).
- docs/index.md TOC extended to 13 rows.

Also fixed numbering drift in docs/12 (duplicate #28, missing #17/#18)
and added Q19 to docs/11 covering the SMB-share verification step.
2026-05-04 22:24:24 +00:00

72 lines
7.5 KiB
Markdown
Raw Blame History

# Instructions for Claude (and other agents)
This file tells future automated runs what they need to know about this repo.
## Repo conventions
- **Documentation:** all docs live in `/docs/` and are numbered. Entry point is `docs/index.md`. When you add a doc, give it the next free `NN-` prefix and add a row to the index TOC.
- **Runtime artifacts:** live in `nexa-core/` (workflows, prompts, configs, scripts). Don't put `.md` documentation in there — link from `/docs/` instead.
- **Source-of-truth:** if a doc duplicates content from `nexa-core/config/*.md`, **delete the duplicate**. Single source of truth.
## Real infrastructure (verified from screenshots, May 2026)
- **Proxmox host** `nuc` at `192.168.1.20:8006` (PVE 9.1.9, kernel 6.17.13-4-pve, EFI).
- Hardware: **22 threads** (Intel Core Ultra 7 155H, 1 socket), **62 GiB RAM**, **1.64 TiB disk**.
- Steady state: ~32 GiB used (≈24 GiB of which is ZFS ARC, tunable via `zfs_arc_max`), CPU load <2.0, IO delay <0.05%.
- LXC 102 dns (AdGuard) — internal DNS, rewrites for `*.nuclide.systems`.
- LXC 103 backrest — backup orchestration.
- LXC 104 docker — main docker host at `192.168.1.40`, hostname `docker`, OS Debian 13. **Unprivileged**, provisioned from the **Dockge** flavor of `proxmox-helper-scripts` — stacks are managed in the Dockge web UI, not raw `docker compose` on disk. Allocated: 16 CPU, 31.25 GiB RAM (25% used), 8 GiB swap, 200 GiB boot disk (47.7% used). **Storage on the UNAS (`192.168.1.31`)** is reachable two ways:
- **NFS** (Proxmox host-mounted at `/mnt/pve/unas`, 19.4 TiB / 16.3 TiB free) — fine for host-side admin tasks and read-mostly mounts.
- **SMB** — **default for Nexa per-container volumes**. The user already hit NFS+unprivileged-LXC write-permission issues with Nextcloud; don't repeat that. Mount SMB shares directly as docker volumes inside the stack with explicit `username=`/`uid=`/`gid=` — sidesteps uid-mapping entirely.
**UNAS layout conventions** (homelab-wide, all docker containers follow them):
- **`services/<svc>/` is the general docker config store** — every container in LXC 104 binds its persistent data here. Existing tenants observed: immich, karakeep, nextcloud, ntfy, paperless-ai, pocketid, shelfmark, stremio, traccar, vaultwarden, gluetun. **Stale (retire, do not consume):** `services/siyuan/` (migrated to Obsidian) and `services/open-webui/` (unused). **Nexa MUST follow the same pattern: `services/nexa/{qdrant,tei-cache,graphdb,...}`.** Don't invent a parallel layout.
- `backup/<svc>/` — per-service backups (existing: home-assistant tars, immich pgdump, nextcloud borg). **Nexa snapshots → `backup/nexa/`.**
- `media/`, `code/`, `_sortMe/`, `dump/`, `test_perm` — user data, not Nexa's concern.
- **Before deploying any Nexa container, READ AN EXISTING STACK** (e.g. `services/karakeep/` or `services/immich/`'s compose under Dockge) to confirm the exact mount syntax in use — driver name, share path, credential injection pattern. Match it. The actual NFS export root is `/var/nfs/shared/storage`; the SMB share name is **still TBD — see Q19** in `docs/11`.
**Hard-blocklist for any Nexa indexer / agent** (never read these paths or matching glob):
- `_sortMe/wallet/**` — contains PGP keys + bitcoin wallet files.
- Any path matching `*.gpg`, `*.asc`, `*.key`, `*.pem`, `id_rsa*`, `*wallet*`, `*.kdbx`, `*credentials*`, `*secret*`.
- The Nextcloud appdata dir (`services/nextcloud/appdata_*`) — Nextcloud-internal, not user content. Intel iGPU passthrough is *configured but currently broken* — see [docs/12 #26](./docs/12-optimization-opportunities.md#26).
- LXC 105 nextcloud — Nextcloud at `nc.nuclide.systems`.
- LXC 106 octoprint — currently *Exited*; flagged in [docs/11](./docs/11-open-questions.md#q13).
- LXC 108 zoraxy — reverse proxy at `192.168.1.4:8000`, TLS for `*.nuclide.systems`.
- VM 100 haos — Home Assistant.
- **Already-running services on docker host** (don't redeploy):
- Memos `:5230`, n8n `:5678`, LiteLLM `:4000` (UI LobeHub `:3210`), Qdrant (`qdrant_scientific`), ntfy `:7998`, Karakeep (legacy alias `hoarder.nuclide.systems`), Vaultwarden `:11001`, Pocket-ID `:1411`, Immich, Audiobookshelf, Paperless-ngx, Traccar, Prowlarr, plus MCP containers (`crawl4ai-mcp`, `markitdown-mcp`, `papersearch-mcp`).
- **Octoprint (LXC 106)** is *intentionally* powered down most of the time. Phase-5 monitoring must skip names matching `octoprint*` rather than alert on its Exited state.
- **Obsidian vault lives inside Nextcloud** at `nc.nuclide.systems/Notizen/` (multi-device sync via Nextcloud client). Nexa accesses it via WebDAV — read-only, no filesystem mount. Ignore list: `.copilot/`, `.copilot-index/`, `.smart-env/`, `.caldav-sync/`, `assets/` (visual queue, Phase 3.2), `Templates/`, `BMO/`, `Excalidraw/`. Index target: `Notizen/**/*.md`.
- **Nextcloud Tasks lists & calendars** (German names, may grow over time):
- `Persönlich` → Personal context.
- `DLR` → Work context (DLR is the user's employer).
- `Einkaufsliste` → Shopping.
- `Wunschliste` → Wishes.
Lists are discovered **by name** at runtime (Qdrant `_config` namespace caches `name → id`). Never hardcode IDs. The discovery workflow runs daily and on cache-miss; new lists added in Nextcloud are honoured automatically next refresh.
- **Mail = Nextcloud Mail, single account `fkrebs@nucli.de`.** No separate IMAP entry. The `Waiting` folder is a manual user signal — items there are skipped from digests.
- **Auth = Pocket-ID SSO is global** at the Zoraxy layer. Don't add app-level basic-auth to Nexa surfaces; UIs inherit SSO. Machine-to-machine still uses API keys / app passwords.
- **Decided for Nexa** (don't re-litigate without user input):
- Vector store: **reuse `qdrant_scientific`** with collections suffixed by modality (`nexa_knowledge_text`, `nexa_knowledge_visual`).
- Embeddings staged: **Phase 3.1** TEI + `BAAI/bge-m3` (text-only, 1024-dim). **Phase 3.2** swap to `infinity` and add `jinaai/jina-clip-v2` (768-dim, joint text+image space). All forward-compat fields (`modality`, `media_uri`, `graph_iri`, `nexa:pendingVisualIndex`) exist from 3.1 — adding the visual collection is additive.
- Graph store: **Ontotext GraphDB** (SPARQL/RDF), Phase 3.4. RDF schema in docs/08 already includes `nexa:modality` / `nexa:mediaUri` / `nexa:vectorCollection` / `nexa:pendingVisualIndex`.
- Chat model: SAIA via LiteLLM virtual key.
## When working on Nexa
1. **Read `docs/index.md` first** — it's the navigator.
2. **Open questions first.** Before writing code or workflow JSON, scan `docs/11-open-questions.md`. If your task touches an unanswered Q, **stop and ask** rather than picking a default. Append new blockers to that doc as `[ ] Q-NN`.
3. **Optimization findings.** When you spot infrastructure improvements, add them to `docs/12-optimization-opportunities.md` as a numbered bullet — don't just mention them in commit messages.
4. **Never inline secrets** in workflow JSON or `.env` committed to git. Use n8n credentials, LiteLLM virtual keys, or (longer term) Vaultwarden.
5. **Keep deployment minimal.** The default answer to *"do we need a new container?"* is **no** — the existing stack covers most needs.
## Branch policy
- This branch is `claude/organize-docs-deployment-7N4v2`. Push only here unless told otherwise.
- New work for an unrelated feature → new branch under `claude/<topic>`.
## Quick links
- [docs/index.md](./docs/index.md)
- [docs/09-deployment.md](./docs/09-deployment.md) — most-touched file during bring-up
- [docs/11-open-questions.md](./docs/11-open-questions.md) — read **before** assuming defaults
Reference in New Issue View Git Blame Copy Permalink