docs: update all documentation to reflect deployed state (2026-05-09)

- docs/README.md: add full documentation index (was empty) - docs/servers/ROCINANTE.md: create new server doc (RTX 4090, heavy inference) - docs/servers/SERENITY.md: fix CPU spec (dual X5690, not single); add reranker service - docs/architecture/SERVICES_DIRECTORY.md: fill in all service ports (was all dashes) - docs/architecture/ARCHITECTURE_OVERVIEW.md: mark all services as deployed - docs/planning/HOMELAB_EXPANSION_PLAN.md: mark all 6 phases complete
2026-05-09 11:13:05 -05:00
parent 6c19f82a0a
commit d6eafe0989
6 changed files with 300 additions and 309 deletions
--- a/docs/architecture/ARCHITECTURE_OVERVIEW.md
+++ b/docs/architecture/ARCHITECTURE_OVERVIEW.md
@@ -1,107 +1,64 @@
-# Homelab Architecture Overview
+# Architecture Overview

-## Primary Docker Host
-Host: `PlausibleDeniability` (TrueNAS Scale)
+Full homelab stack as of 2026-05-09. All 6 expansion phases are complete and deployed.

-Production Docker workloads run on PlausibleDeniability via standalone Docker Compose stacks.
-TrueNAS Apps (ix-app format) have been fully migrated to compose stacks.
+## Servers

-## Repository Layout
-Repo root: `/mnt/docker-ssd/docker/compose`
-Remote: `git@github.com:Paccoco/truenas-stacks.git`
-Gitea mirror: `https://gitea.paccoco.com/fizzlepoof/truenas-stacks.git`
+| Server | OS | IP | Role |
+|--------|----|----|------|
+| **PlausibleDeniability (PD)** | TrueNAS Scale 25.10.2.1 | 10.5.1.6 | Primary Docker host — all compose stacks |
+| **Serenity** | Unraid 7.2.4 | 10.5.1.5 | NAS, ARR stack, CPU reranker |
+| **N.O.M.A.D.** | Ubuntu 25.10 | 10.5.1.16 | Light Ollama models, game servers |
+| **Rocinante** | (bare metal) | 10.5.1.112 | Heavy Ollama models (RTX 4090) |

-Stack directories:
- `databases/` = shared-postgres, shared-mariadb, shared-redis — deploy FIRST
- `infrastructure/` = newt, homepage, uptime-kuma, dockhand, netdata, tailscale — deploy SECOND
- `media/` = plex, tautulli, audiobookshelf, seerr, calibre-web-automated
- `photos/` = immich server + machine learning
- `home/` = kitchenowl, donetick, dakboard bridge, shlink, shlink-web-client, qui
- `dev/` = gitea, rackpeek
- `ai/` = ollama, openwebui
- `meshtastic/` = meshmonitor, mqtt-proxy, tileserver, meshtastic-map
+## Network

-## Storage Model
+- **LAN subnet:** 10.5.1.0/24
+- **Tailscale:** Serenity reachable at 100.94.87.79
+- **NFS:** Serenity exports `/mnt/user/data` and `/mnt/user/immich` → mounted on PD at `/mnt/unraid/` via post-init script
+- **Docker networking:** Cross-stack communication via named external networks (`ai-services`, `ix-databases_shared-databases`)

-### Local SSD
-Mounted at: `/mnt/docker-ssd`
- Docker data root: `/mnt/docker-ssd/docker/docker-data`
- Databases: `/mnt/docker-ssd/docker/databases/`
- Write-heavy appdata: `/mnt/docker-ssd/docker/appdata/`
- GPU/model storage
- Apps that perform chown or aggressive startup writes
- SQLite-backed apps
+## Stack Overview

-Notable appdata on SSD:
- plex, tautulli, audiobookshelf, seerr, dockhand, rackpeek
- immich, immich-ml, ollama, openwebui
- shlink, gitea, netdata, tailscale, uptime-kuma
+### Infrastructure Layer
+- **Homepage** (3300) — dashboard / service index
+- **Uptime Kuma** (3001) — monitoring and alerting
+- **Gotify** (8443) — push notifications
+- **Gitea** (3002) — self-hosted git
+- **Dockhand** (3230) — Docker management UI

-### TrueNAS Pool (tank)
-Mounted at: `/mnt/tank`
- General appdata: `/mnt/tank/docker/appdata/`
- Backups: `/mnt/tank/docker/backups/`
- Downloads: `/mnt/tank/docker/downloads/`
+### AI Layer
+- **LiteLLM** (4000) — unified LLM proxy; routes to Ollama on N.O.M.A.D. (light) and Rocinante (heavy)
+- **OpenWebUI** (8282) — chat UI with RAG, STT, and web search
+- **Qdrant** (6333/6334) — vector database for RAG
+- **Whisper** (8786) — CUDA speech-to-text on PD's RTX 2080 Ti
+- **SearXNG** (8888) — private web search backend
+- **Reranker** (Serenity:9787) — TEI bge-reranker-v2-m3, CPU-only

-Notable appdata on tank:
- homepage, newt, dockhand (config only)
- kitchenowl, donetick, qui
- calibre-web-automated config
+### Media Layer
+- **Plex** (32400), **Tautulli** (8181), **Audiobookshelf** (13358), **Calibre** (8183), **Seerr** (5055) — all on PD
+- ARR stack on Serenity (Sonarr, Radarr, Prowlarr, qBittorrent)

-### Unraid NFS
-Mounted at: `/mnt/unraid`
- Media libraries: `/mnt/unraid/data/media/`
- Immich media: `/mnt/unraid/immich`
+### Productivity Layer
+- **Immich** (2283) — photo management; library on Serenity NFS
+- **Paperless-NGX** (8083) — document management
+- **Karakeep** (3100) — bookmarks / read-later
+- **n8n** (5678) — workflow automation
+- **KitchenOwl** (8086), **DoneTick** (2021) — household and task management

-## Networks
- `ix-databases_shared-databases` — created by databases stack; project name `ix-databases` set in compose
- `pangolin` — created by newt at runtime; used by all externally exposed services
+### Smart Home Layer
+- **Home Assistant** (8123) — home automation hub
+- **Kima Hub** (3333) — custom IoT gateway

-## Active Stacks (as of 2026-05-05)
+### Monitoring Layer
+- **Grafana** (3000) + **Prometheus** (9090) — metrics and dashboards
+- **MeshMonitor** (8081) — network mesh visibility

-### databases/
- shared-postgres (immich-optimized image with vectorchord + pgvector)
- shared-mariadb
- shared-redis
+## Key Architectural Decisions

-### infrastructure/
- newt, homepage, dockhand, uptime-kuma, netdata, tailscale
-
-### media/
- ix-plex-plex-1 (GPU passthrough, RTX 2080 Ti)
- ix-tautulli-tautulli-1
- ix-audiobookshelf-audiobookshelf-1
- seerr (Postgres backend)
- calibre-web-automated
-
-### photos/
- ix-immich-immich-server-1
- ix-immich-immich-machine-learning-1 (GPU, CUDA)
-
-### home/
- kitchenowl, donetick, donetick-dakboard-bridge, qui, shlink, shlink-web-client
-
-### dev/
- gitea, ix-rackpeek-rackpeek-1
-
-### ai/
- ollama (GPU, RTX 2080 Ti, port 11434)
- openwebui (Postgres backend, port 8282)
-
-### meshtastic/
- meshmonitor, meshmonitor-mqtt-proxy, meshmonitor-tileserver, meshtastic-map
-
-## Planned / Not Yet Deployed
- dispatcharr, gotify, bytestash, kima-hub, n8n, qdrant, paperless-ngx, home-assistant
-
-## Shelved
- scriberr — SQLite incompatible with ZFS nfsv4 ACLs
-
-## Design Principles
- deterministic storage paths
- no anonymous volumes
- stack-local .env for secrets; .env.example committed with placeholders
- SSD for write-heavy / DB / SQLite / GPU workloads
- tank NFS for general appdata and configs
- Unraid NFS for media only
- databases stack uses `name: ix-databases` to maintain network name compatibility
+1. **LiteLLM as unified proxy** — all AI clients target LiteLLM; model routing is transparent to clients
+2. **Reranker on Serenity (CPU)** — frees RTX 2080 Ti on PD exclusively for Whisper CUDA; CPU latency acceptable for RAG reranking
+3. **External Docker networks** — `ai-services` bridges all AI containers across compose files; `ix-databases_shared-databases` provides shared DB access
+4. **NFS for Immich** — photo library lives on Serenity's large array; PD mounts on demand (not at boot)
+5. **TrueNAS manages Docker** — never use `systemctl restart docker` on PD; use `docker compose` or `docker restart` for individual containers
+6. **Credential hygiene** — Gitea remote uses HTTPS + credential store; GitHub remote uses SSH key (`/root/.ssh/id_gitea`)