16 KiB
16 KiB
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 + apt-mark hold on all other installed kernel packages (as of 2026-08-11) — see gotchas |
🖥️ 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 — live over HTTPS as of 2026-08-11 (Docker/nginx/SSL/DNS done); Authelia decision + first admin login 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_containersoutput 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.mdDNS 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 |
| collections.spendlik.sk | 340219244 |
| pdf.spendlik.sk | (add after DNS record created in WebSupport) |
| cal.spendlik.sk | (add after DNS record created in WebSupport — Radicale not yet deployed) |
⚠️ When adding a new subdomain: (1) create CNAME record →
spendlik.skin 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: live over HTTPS, Authelia + first login 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_contentto find relevant files by keyword instead of guessing filenames. 💡 Files01_through11_referenced previously do not exist — they were placeholders never written. 💡 For "is CT X running/deployed right now" questions, don't read docs — callproxmox_list_containersdirectly (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) againsthomelab-overview.mdandobsidian-vault/05 Resources/Proxmox LXC Templates.md— guides can go stale. SeePROJECT_INSTRUCTIONS.md→ Pre-Flight Verification. 💡 Also verify nginx vhost naming convention (full domain, not short service name) and which CT nginx work belongs on (CT 101, never the app container) before giving nginx-related steps — see114_koillection_deployment.mdPhase 6 gotchas for a concrete example of both mistakes happening in the same deployment.
🔑 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 (proxmox-boot-tool kernel pin). 2026-08-11 incident: an accidental apt upgrade -y run directly on the Proxmox host (meant for a container) pulled in proxmox-kernel-6.14.11-9-pve and the entire proxmox-kernel-7.0.x branch. No impact occurred — the boot pin held, running kernel never changed, NVIDIA DKMS module remained built against the pinned 6.14.11-5-pve only. Resolved by re-affirming the pin and running apt-mark hold proxmox-kernel-6.14 proxmox-kernel-7.0 proxmox-kernel-6.14.11-9-pve proxmox-kernel-7.0.14-11-pve-signed proxmox-kernel-7.0.6-2-pve, which now blocks apt from proposing these kernel packages at all. Verify hold status with apt-mark showhold before assuming any future apt upgrade on the host is kernel-safe. |
| 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. |
| nginx vhosts belong on CT 101 only | Never install or configure nginx on an app's own container — all reverse-proxy work happens on CT 101. Check the shell prompt if unsure which container you're in. |
| nginx vhost filenames | Named by full domain (e.g. collections.spendlik.sk), not by short service name — verify with ls /etc/nginx/sites-available/ on CT 101 before writing a new one. |
| 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. |
| NVIDIA driver on host shows as unavailable | nvidia-smi failing on the Proxmox host with "couldn't communicate with the NVIDIA driver" is expected, not a fault, whenever VM 110 is running with GPU passthrough active — the GPU is owned by vfio-pci for the VM, not the host. Only investigate if VM 110 is stopped and the host still can't see the GPU. |
🔄 Active Projects (as of 2026-08-11)
| Project | Next Action | Reference |
|---|---|---|
| Koillection | Live over HTTPS (https://collections.spendlik.sk) — decide Authelia vs. bypass (Phase 9), then first admin login + collection setup (Phase 10–11) |
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
✅ Recently Resolved
| Item | Resolution |
|---|---|
Accidental apt upgrade -y on Proxmox host (2026-08-11) |
Ran against host instead of a container; pulled in 6.14.11-9-pve + 7.0.x kernel packages. Boot pin held throughout, no actual impact on running kernel or NVIDIA passthrough. Sealed with proxmox-boot-tool kernel pin 6.14.11-5-pve (reaffirmed) + apt-mark hold on all 5 non-pinned kernel packages. Verified via apt-mark showhold. |
🧠 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 |