221 lines
14 KiB
Markdown
221 lines
14 KiB
Markdown
# 00 — Master Index
|
||
> Last updated: 2026-08-11
|
||
> Quick-reference card for Claude. Read this first, then load specific files only as needed.
|
||
|
||
---
|
||
|
||
## 🏠 Infrastructure Constants
|
||
|
||
| Key | Value |
|
||
|---|---|
|
||
| **Proxmox host** | `192.168.1.48:8006` |
|
||
| **Gateway** | `192.168.1.1` |
|
||
| **NAS** | `192.168.1.12` (Synology, spendlikstation.local) |
|
||
| **Domain** | `spendlik.sk` |
|
||
| **WebSupport service ID** | `15056760` |
|
||
| **Gitea owner** | `spendlik` |
|
||
| **MCP server** | `mcp.spendlik.sk` (CT 112, port 3500) |
|
||
| **Proxmox kernel** | `6.14.11-5-pve` PINNED — 6.17.x and 7.0.x installed but won't boot |
|
||
|
||
---
|
||
|
||
## 🖥️ Container & VM Inventory
|
||
|
||
| ID | Hostname | IP | Domain | Purpose |
|
||
|---|---|---|---|---|
|
||
| 100 | n8n | 192.168.1.29 | automation.spendlik.sk | Workflow automation (Authelia protected) |
|
||
| 101 | reverse-proxy | 192.168.1.10 | — | nginx reverse proxy for all services |
|
||
| 102 | authelia | 192.168.1.50 | auth.spendlik.sk | SSO / 2FA gateway |
|
||
| 103 | matrix-synapse | 192.168.1.60 | matrix.spendlik.sk | Self-hosted messaging |
|
||
| 104 | snappymail | 192.168.1.55 | email.spendlik.sk | Webmail (Authelia protected) |
|
||
| 105 | audiobookshelf | 192.168.1.70 | books.spendlik.sk | Ebooks / audiobooks (NAS bind mount) |
|
||
| 106 | jellyfin | 192.168.1.75 | jellyfin.spendlik.sk | Media server (NAS NFS mount) |
|
||
| 107 | wireguard | 192.168.1.80 | — | VPN (UDP 51820) |
|
||
| 108 | ddns | 192.168.1.95 | — | DDNS updater (WebSupport API v2) |
|
||
| 109 | gitea | 192.168.1.90 | git.spendlik.sk | Self-hosted Git (v1.22.6, code indexer enabled) |
|
||
| 110 | windows11 (VM) | 192.168.1.227 | — | RTX 4060 passthrough, Rhino 7 + Sunshine/Moonlight |
|
||
| 111 | paperless | 192.168.1.111 | paperless.spendlik.sk | Document management (6-lang OCR, media+data on NAS) |
|
||
| 112 | mcp-server | 192.168.1.100 | mcp.spendlik.sk | MCP bridge — Proxmox + Gitea tools for Claude |
|
||
| 114 | koillection | 192.168.1.114 | collections.spendlik.sk | Collection manager — CT created 2026-08-11, **app deployment in progress** (Docker/Koillection/nginx/SSL/DNS still pending, see `114_koillection_deployment.md`) |
|
||
| 115 | vaultwarden | 192.168.1.115 | vault.spendlik.sk | Password manager (Vaultwarden, Docker, Bitwarden-compatible) |
|
||
|
||
> ⚠️ CT 117 (Radicale) has a deployment guide written but is **NOT yet deployed** — do not treat as live infrastructure. It will be added to this table once physically provisioned.
|
||
> ⚠️ CT 113 (stirling-pdf) is documented elsewhere in this repo but does **not** appear in live `proxmox_list_containers` output as of 2026-08-11 — flagged for investigation, do not assume it's running without checking live state first.
|
||
> Next available CT ID: **116** (Bookmark Manager, undecided tool) · CT 117 reserved for Radicale.
|
||
|
||
---
|
||
|
||
## 🌐 WebSupport DNS Record IDs
|
||
|
||
Script location: `/usr/local/bin/ddns-update.sh` in CT 108. Full credentials map: `secrets-index.md`.
|
||
> Since 2026-08-10: all subdomains are **CNAME → spendlik.sk**; only the root record holds an IP and is updated by the DDNS script. See `homelab-overview.md` DNS architecture section.
|
||
|
||
| Subdomain | Record ID |
|
||
|---|---|
|
||
| spendlik.sk | 12631197 |
|
||
| *.spendlik.sk | 12631200 |
|
||
| automation.spendlik.sk | 306256338 |
|
||
| matrix.spendlik.sk | 307776273 |
|
||
| email.spendlik.sk | 308845857 |
|
||
| auth.spendlik.sk | 308994393 |
|
||
| books.spendlik.sk | 311013228 |
|
||
| jellyfin.spendlik.sk | 311384664 |
|
||
| git.spendlik.sk | 323271195 |
|
||
| mcp.spendlik.sk | 327475181 |
|
||
| paperless.spendlik.sk | 328109687 |
|
||
| vault.spendlik.sk | 330343277 |
|
||
| pdf.spendlik.sk | *(add after DNS record created in WebSupport)* |
|
||
| collections.spendlik.sk | *(add after CNAME record created in WebSupport — Koillection app deployment in progress)* |
|
||
| cal.spendlik.sk | *(add after DNS record created in WebSupport — Radicale not yet deployed)* |
|
||
|
||
> ⚠️ When adding a new subdomain: (1) create **CNAME** record → `spendlik.sk` in WebSupport admin (never a per-subdomain A record), (2) add nginx vhost in CT 101, (3) run certbot, (4) inspect nginx config after certbot. No DDNS script edit needed — see above.
|
||
|
||
---
|
||
|
||
## 💻 Devices
|
||
|
||
| Device | OS | Key Detail |
|
||
|---|---|---|
|
||
| Main PC | CachyOS (Arch), KDE Plasma 6 / Wayland | i7-13700K, RTX 4060 Ti, 32GB DDR5 |
|
||
| Galaxy S25 | Android | WireGuard VPN client; MGit for Obsidian sync; Bitwarden |
|
||
| Galaxy Tab S9 | Android | MGit for Obsidian sync; Bitwarden |
|
||
| Bambu A1 + AMS Lite | — | LAN Only Mode, OrcaSlicer |
|
||
|
||
---
|
||
|
||
## 📁 Documentation Map
|
||
|
||
| File | Covers |
|
||
|---|---|
|
||
| `homelab-overview.md` | Hardware specs, full container/VM table, NAS mounts, network diagram, **DNS architecture (CNAME-based, updated 2026-08-10)** |
|
||
| `cachy-overview.md` | CachyOS main PC — hardware, software, kernel, services, keyboard customisation |
|
||
| `services.json` | Structured inventory of all containers/VMs — IPs, ports, stacks, compose paths |
|
||
| `secrets-index.md` | Map of service credentials and WHERE they are stored (no actual secrets) |
|
||
| `PROJECT_INSTRUCTIONS.md` | Canonical behavioural/methodology reference — decision defaults, checklists, gotchas, **Pre-Flight Verification protocol (added 2026-08-11)** |
|
||
| `113_stirling_pdf_deployment.md` | CT 113 — Stirling PDF Docker deploy, nginx, SSL, n8n API integration |
|
||
| `114_koillection_deployment.md` | CT 114 — Koillection Docker deploy, NAS uploads mount, collection setup — **IN PROGRESS: CT created 2026-08-11, app install pending** |
|
||
| `115_vaultwarden_deployment.md` | CT 115 — Vaultwarden Docker deploy, nginx, SSL |
|
||
| `117_radicale_deployment.md` | CT 117 — Radicale CalDAV/CardDAV deploy, nginx, SSL, Thunderbird/DAVx⁵ clients — **guide only, not yet deployed** |
|
||
|
||
> 💡 Load only the file(s) relevant to the current task. Do not load all files by default.
|
||
> 💡 Use `gitea_search_content` to find relevant files by keyword instead of guessing filenames.
|
||
> 💡 Files `01_` through `11_` referenced previously do not exist — they were placeholders never written.
|
||
> 💡 For "is CT X running/deployed right now" questions, don't read docs — call `proxmox_list_containers` directly (single cheap live call, always accurate).
|
||
> 💡 Before running Phase 1 of any not-yet-executed deploy guide, verify volatile values (LXC template version, DNS record type) against `homelab-overview.md` and `obsidian-vault/05 Resources/Proxmox LXC Templates.md` — guides can go stale. See `PROJECT_INSTRUCTIONS.md` → Pre-Flight Verification.
|
||
|
||
---
|
||
|
||
## 🔑 Key Gotchas
|
||
|
||
| Area | Warning |
|
||
|---|---|
|
||
| **nginx / certbot** | Certbot corrupts configs — always inspect after issuance; check for duplicate `server_name` and missing closing braces |
|
||
| **NFS mounts** | Use `soft,timeo=30,retrans=3` — hard NFS can freeze Proxmox host |
|
||
| **DDNS script** | `/tmp/ddns_last_ip` cache persists at runtime; cleared on reboot. Since 2026-08-10 only updates the root A record — no per-subdomain edits needed. |
|
||
| **WebSupport DNS** | Two separate management pages — missing the second caused an outage. DNS record must exist before certbot can verify. Always update both pages. |
|
||
| **WebSupport DNS — subdomains are CNAME-only** | Since 2026-08-10: all `*.spendlik.sk` subdomains are CNAME → `spendlik.sk`. Only the root A record ever holds an IP — WebSupport rejects (422) writing an A record whose IP value already exists on *any other record* in the zone. |
|
||
| **WebSupport API — PUT silently resets `name`** | A `PUT` to `/v2/service/{id}/dns/record/{recordId}` that omits the `name` field does NOT preserve the existing name — it silently renames the record to the bare zone apex. Always include `name` explicitly in PUT payloads, or avoid partial-field updates. |
|
||
| **WebSupport API — POST `name` is relative** | Creating a record via POST: `name` is relative to the zone, not a full FQDN. Passing `"email.spendlik.sk"` creates `email.spendlik.sk.spendlik.sk`. Use the bare subdomain only (`"email"`, `"*"`, `"git"`). |
|
||
| **Gitea writes** | Always read file content before writing — writes replace entire file |
|
||
| **Proxmox kernel** | PINNED to `6.14.11-5-pve`. Do NOT unpin or upgrade without verifying NVIDIA 550 DKMS support first |
|
||
| **LXC template versions** | Verify exact template filename in `obsidian-vault/05 Resources/Proxmox LXC Templates.md` (or live `pveam list local`) before every `pct create` — versions bump periodically and guides can reference stale strings. Once a container is created, template version is irrelevant — `apt upgrade` keeps it current, no need to recreate existing containers on a newer template. |
|
||
| **OpenRGB** | Uninstalled — SMBus interaction with ADATA XPG GAMMIX D35 poses hardware risk. Do not reinstall. |
|
||
| **Hairpin NAT** | Slovak Telekom router blocks hairpin — test external domains from mobile data, not LAN |
|
||
| **WebSupport API auth** | HMAC-SHA1 signed requests; `X-Date` header in `YYYYMMDDTHHmmSSZ` format; service ID is numeric `15056760` |
|
||
| **kocka-novinky.sk** | Wordfence blocks login — keep disabled. wp-config.php WP_SITEURL/WP_HOME hardcoded. Zen browser Content-Encoding issue — use Firefox/Chrome. |
|
||
| **Paperless consume** | File watcher only detects new files — use `document_consumer --oneshot` for bulk imports |
|
||
| **LXC Docker** | Requires `--unprivileged 0 --features nesting=1` for Docker to work inside container |
|
||
| **Stirling PDF nginx** | Set `client_max_body_size 100M` — large PDFs will be rejected without it |
|
||
| **Stirling PDF + Authelia** | Add `/api/*` bypass rule before catch-all 2FA rule — required for n8n API access |
|
||
| **Koillection HTTPS** | Set `HTTPS_ENABLED=1` in `.env` and restart the container after SSL is in place — otherwise redirect loops |
|
||
| **Koillection upgrades** | Always back up PostgreSQL DB before upgrading — data migrations can have edge cases |
|
||
| **Radicale + Authelia** | CalDAV clients use Basic Auth on every request, not browser SSO — bypass Authelia for `cal.spendlik.sk`, rely on Radicale htpasswd + HTTPS instead |
|
||
| **pveproxy crash** | `Can't call method "process" on an undefined value at pveproxy.pm line 304` — seen 2026-07-28, likely NFS-cascade freeze (host + SSH fully unresponsive). Fix: physical power cycle. Confirmed **all CTs (100–115) + VM 110 now set to "Start at boot"** as of 2026-07-28, so recovery should be automatic next time. |
|
||
|
||
---
|
||
|
||
## 🔄 Active Projects (as of 2026-08-11)
|
||
|
||
| Project | Next Action | Reference |
|
||
|---|---|---|
|
||
| Koillection | CT 114 created 2026-08-11 — continue with Phase 2 (Docker install) onward | CT 114 |
|
||
| kocka-novinky.sk automation | Build n8n POC: Brickset → Claude API → WordPress lego-set + post | CT 100 |
|
||
| Paperless-ngx | ~730 docs processing; next: Gemini post-processing setup | CT 111 |
|
||
| Gemini post-processing | Get Gemini API key → install Python package in CT 111 | CT 111 |
|
||
| WireGuard DDNS | Add `vpn.spendlik.sk` DNS record + update CT 108 script | CT 107/108 |
|
||
| Bookmark manager | Decide tool → deploy CT 116 | CT 116 (free) |
|
||
| Authelia enforcement | Extend 2FA to Jellyfin, Audiobookshelf, Gitea | CT 102/101 |
|
||
| Radicale (CalDAV) | Guide written (`117_radicale_deployment.md`) — not yet deployed | CT 117 |
|
||
| Investigate pveproxy/NFS crash | Check dmesg/NFS logs around 2026-07-28 16:45–17:40 UTC to confirm root cause | Proxmox host |
|
||
| Investigate CT 113 discrepancy | Documented as deployed but absent from live `proxmox_list_containers` — confirm actual state | CT 113 |
|
||
|
||
> Full task list: `obsidian-vault/Tasks.md`
|
||
|
||
---
|
||
|
||
## 🧠 Life OS — Obsidian Vault Structure
|
||
|
||
| Folder | Purpose |
|
||
|---|---|
|
||
| `00 Inbox` | Capture everything first |
|
||
| `01 Goals` | Long-term goals |
|
||
| `02 Projects` | Active projects (each has its own `.md`) |
|
||
| `03 Areas` | Ongoing responsibilities (Homelab, Main PC, Personal Admin) |
|
||
| `04 Daily Notes` | Daily log |
|
||
| `05 Resources` | Reference material |
|
||
| `06 Archive` | Completed projects |
|
||
| `Tasks.md` | Master task dashboard (hand-curated) |
|
||
|
||
**Sync**: Obsidian Git plugin on PC → Gitea `spendlik/obsidian-vault`; MGit on Android
|
||
|
||
### 📋 Vault Quick Reference — Known File Paths
|
||
|
||
| File | Purpose |
|
||
|---|---|
|
||
| `Tasks.md` | Live task dashboard |
|
||
| `05 Resources/Possible Purchases.md` | Purchase wishlist |
|
||
| `05 Resources/3D Print Queue.md` | 3D print job queue |
|
||
| `05 Resources/Proxmox LXC Templates.md` | LXC template reference — **verify before every `pct create`** |
|
||
| `03 Areas/Personal Admin.md` | Personal admin tasks |
|
||
| `03 Areas/Homelab.md` | Homelab recurring tasks |
|
||
| `03 Areas/Main PC.md` | CachyOS main PC tasks |
|
||
|
||
---
|
||
|
||
## 🛠️ Automation & Tools Stack
|
||
|
||
| Layer | Tool | Location |
|
||
|---|---|---|
|
||
| Scheduling / plumbing | n8n | CT 100 / automation.spendlik.sk |
|
||
| AI content generation | Claude API (claude-sonnet-4-20250514) | via n8n HTTP node |
|
||
| Agentic coding assistant | Claude Code 2.1.173 | CachyOS / VSCodium extension |
|
||
| MCP tools | Proxmox + Gitea + search | CT 112 / mcp.spendlik.sk |
|
||
| Notifications | Matrix | CT 103 / matrix.spendlik.sk |
|
||
| DNS management | WebSupport REST API v2 | CT 108 |
|
||
| Password manager | Vaultwarden | CT 115 / vault.spendlik.sk |
|
||
| Affiliate site | WordPress on WebSupport | kocka-novinky.sk |
|
||
|
||
### MCP Tools Available
|
||
|
||
| Tool | Description |
|
||
|---|---|
|
||
| `proxmox_list_containers` | List all LXC/VMs with status |
|
||
| `proxmox_get_resources` | Node CPU/RAM/disk usage |
|
||
| `proxmox_get_container_status` | Status of specific CT by vmid |
|
||
| `proxmox_start_container` | Start a stopped CT |
|
||
| `proxmox_stop_container` | Stop a running CT |
|
||
| `gitea_list_repos` | List repos for a user |
|
||
| `gitea_read_file` | Read file from any repo |
|
||
| `gitea_write_file` | Write/update file in any repo |
|
||
| `gitea_list_files` | List files in a repo directory |
|
||
| `gitea_search_content` | Full-text search across all .md files in a repo |
|
||
|
||
---
|
||
|
||
## 🗃️ Gitea Repositories
|
||
|
||
| Repo | Visibility | Purpose |
|
||
|---|---|---|
|
||
| `Claude_Homelab` | Public | Infrastructure docs, deploy guides, this index |
|
||
| `obsidian-vault` | Private | Life OS / second brain / task dashboard |
|