docs: add full homelab documentation structure

2026-05-05 14:43:09 -05:00
parent ee8a412a69
commit 370998b8d5
20 changed files with 1405 additions and 24 deletions
--- a/docs/planning/HOMELAB_EXPANSION_PLAN.md
+++ b/docs/planning/HOMELAB_EXPANSION_PLAN.md
@@ -0,0 +1,106 @@
+# Homelab Expansion Plan
+
+## Deployment Order
+1. **Gotify** — unified notification bus, unblocks all n8n workflows
+2. **Qdrant** — vector DB, unblocks proper RAG pipeline
+3. **n8n** — automation backbone, ties everything together
+4. **Paperless-NGX** — document intelligence
+5. **Home Assistant** — home automation layer
+6. **Grafana + Prometheus** — unified observability
+
+---
+
+## Phase 1 — Notifications (Gotify)
+**Host:** PlausibleDeniability
+**Stack:** `/mnt/docker-ssd/docker/compose/automation/`
+**Storage:** appdata on SSD (SQLite backend)
+**Network:** pangolin (expose as `gotify.paccoco.com`)
+
+Single output target for all n8n workflows and homelab alerts.
+
+---
+
+## Phase 2 — Vector Database (Qdrant)
+**Host:** PlausibleDeniability
+**Stack:** `/mnt/docker-ssd/docker/compose/ai/`
+**Storage:** appdata on SSD
+
+Feed it: homelab markdown docs, Gitea commit history, Plex/Tautulli metadata, Obsidian notes.
+
+---
+
+## Phase 3 — Workflow Automation (n8n)
+**Host:** PlausibleDeniability
+**Stack:** `/mnt/docker-ssd/docker/compose/automation/`
+**Storage:** config on tank, Postgres backend
+**Network:** pangolin (`n8n.paccoco.com`) + ix-databases_shared-databases
+
+### Planned Workflows
+- Sonarr/Radarr webhook → Discord + Gotify notification with poster art
+- Tautulli play start → log to Postgres
+- Nightly watch history → Ollama → weekly digest via Gotify
+- Poll Uptime Kuma → cross-reference Netdata → rich alert via Gotify
+- Gitea commit to truenas-stacks → Gotify notification with Ollama summary
+- qBittorrent torrent complete → trigger Sonarr/Radarr rescan
+- KitchenOwl grocery list change → shopping list via Gotify
+- Donetick task due → Gotify reminder
+- Long and Low Crafts order → Donetick task + Gotify DM
+
+---
+
+## Phase 4 — Document Intelligence (Paperless-NGX)
+**Host:** PlausibleDeniability
+**Network:** pangolin (`paperless.paccoco.com`) + ix-databases_shared-databases
+
+OCR and full-text search. Key for Long and Low Crafts invoices, receipts, and manuals.
+
+---
+
+## Phase 5 — Home Automation (Home Assistant)
+**Host:** PlausibleDeniability or N.O.M.A.D.
+**Storage:** config on SSD (SQLite, write-heavy)
+**Network:** host networking recommended for device discovery
+
+---
+
+## Phase 6 — Observability (Grafana + Prometheus)
+**Host:** N.O.M.A.D.
+**Storage:** Prometheus data on hdd-1 or hdd-2
+
+Metrics to scrape: ZFS pool health, container CPU/RAM, Plex streams, qBittorrent, Tailscale latency, Netdata endpoints.
+
+---
+
+## Multi-Model Routing Strategy
+
+| Machine | GPU | Model | Use Case |
+|---|---|---|---|
+| ROCINANTE | RTX 4090 (24GB) | qwen3:32b / deepseek-r1:32b | Heavy reasoning, long context |
+| PlausibleDeniability | RTX 2080 Ti (11GB) | qwen2.5:14b | General homelab assistant, RAG |
+| N.O.M.A.D. | GTX 1080 (8GB) | phi4 / llama3.2:3b | Fast local inference |
+
+---
+
+## Additional Tools
+- **Continue.dev** — VS Code plugin, local Copilot alternative
+- **Obsidian + Gitea Sync** — personal notes → RAG pipeline
+- **Homepage Ollama Widget** — VRAM usage dashboard widget
+- **kima-hub** — self-hosted Spotify alternative
+- **dispatcharr** — planned
+- **bytestash** — planned
+
+---
+
+## Target Architecture
+
+```
+Triggers (Sonarr, Radarr, Tautulli, Gitea, Home Assistant, schedules, email)
+        ↓
+      n8n (routing, logic, orchestration)
+        ↓
+    Ollama (intelligence — model selected by complexity)
+      ↓  ↑
+    Qdrant (semantic context retrieval)
+        ↓
+     Outputs (Gotify → phone, Donetick tasks, Postgres logging, Discord)
+```
--- a/docs/planning/TODO.md
+++ b/docs/planning/TODO.md
@@ -0,0 +1,43 @@
+# Homelab TODO
+
+## Security (do ASAP)
+- [ ] Regenerate Wings token on N.O.M.A.D. (was exposed in chat)
+- [ ] Regenerate N.O.M.A.D. Newt secret (was exposed in chat)
+
+## Infrastructure
+- [ ] Deploy Pi-hole ×2 (primary on PD + backup on Serenity or Pi4)
+- [ ] Set up off-site backup for vital data (appdata, databases, config repo, photos)
+- [ ] Remove dead Unraid-Cloudflared-Tunnel container from Serenity
+- [ ] Serenity malcolm pool capacity planning (heavily utilized)
+- [ ] Add Pangolin resource for `ai.paccoco.com` → openwebui (port 8282)
+- [ ] Add Cloudflare DNS A record for `ai.paccoco.com`
+- [ ] Install fresh editor on PD
+- [ ] Set up private Gitea repo for .env file backups
+
+## AI Stack
+- [ ] Pull `qwen2.5:14b` on PD ollama: `sudo docker exec -it ollama ollama pull qwen2.5:14b`
+- [ ] Create OpenWebUI account and set system prompt from HOMELAB_AI_CONTEXT.md
+- [ ] Disable signups in OpenWebUI after creating account
+- [ ] Connect desktop Ollama to OpenWebUI (Admin → Settings → Connections)
+- [ ] Set `OLLAMA_HOST=0.0.0.0` on desktop and restart Ollama service
+
+## Planned Deployments (PD)
+- [ ] dispatcharr
+- [ ] gotify
+- [ ] bytestash
+- [ ] kima-hub
+- [ ] n8n
+- [ ] qdrant
+- [ ] paperless-ngx
+
+## Healthchecks
+- [ ] Add healthcheck to ix-plex-plex-1
+- [ ] Add healthcheck to ix-tailscale-tailscale-1
+- [ ] Add healthcheck to ix-newt-newt-1
+- [ ] Add healthcheck to ollama (no curl/wget — needs /proc/net/tcp6 or custom solution)
+- [ ] Document and add healthchecks for meshtastic stack
+
+## Documentation
+- [ ] Document meshtastic stack fully (see docs/reference/MESHTASTIC.md)
+- [ ] Fill in port/URL columns in SERVICES_DIRECTORY.md
+- [ ] Document N.O.M.A.D. containers (start_nomad.sh services)