fizzlepoof/truenas-stacks
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 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
This commit is contained in:
Fizzlepoof
2026-05-09 11:14:04 -05:00
parent 6c19f82a0a
commit d44e777a38
6 changed files with 300 additions and 309 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
docs/architecture/ARCHITECTURE_OVERVIEW.md
View File

@@ -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`)

179
docs/architecture/SERVICES_DIRECTORY.md
View File

@@ -1,103 +1,90 @@
# Services Directory
All running services across the homelab with ports, URLs, and backend info.
All homelab services, their hosts, ports, and current status.
## PlausibleDeniability
*Last updated: 2026-05-09*
### Databases (internal only)
| Service | Port | Backend | Notes |
|---------|------|---------|-------|
| shared-postgres | 5432 | — | immich-optimized, vectorchord + pgvector |
| shared-mariadb | 3306 | — | |
| shared-redis | 6379 | — | |
### Infrastructure
| Service | Internal Port | Public URL | Notes |
|---------|--------------|------------|-------|
| newt | — | — | Pangolin reverse proxy agent |
| homepage | — | — | Dashboard |
| dockhand | — | — | Container management |
| uptime-kuma | — | — | MariaDB backend |
| netdata | — | — | Metrics |
| tailscale | — | — | VPN |
### Media
| Service | Internal Port | Public URL | Notes |
|---------|--------------|------------|-------|
| plex | — | — | GPU passthrough, RTX 2080 Ti |
| tautulli | — | — | Plex analytics |
| audiobookshelf | — | — | Audiobooks |
| seerr | — | — | Postgres backend |
| calibre-web-automated | — | — | Ebooks |
### Photos
| Service | Internal Port | Public URL | Notes |
|---------|--------------|------------|-------|
| immich-server | — | — | Postgres + Redis, GPU |
| immich-ml | — | — | GPU, CUDA |
### Home
| Service | Internal Port | Public URL | Notes |
|---------|--------------|------------|-------|
| kitchenowl | — | — | Grocery/tasks |
| donetick | — | — | Postgres backend, selfhosted.yaml required |
| shlink | — | — | URL shortener, Postgres |
| shlink-web-client | — | — | |
| qui | — | — | qBittorrent UI, manages Serenity remotely |
### Dev
| Service | Internal Port | Public URL | Notes |
|---------|--------------|------------|-------|
| gitea | — | gitea.paccoco.com | Postgres backend |
| rackpeek | — | — | |
### AI
| Service | Internal Port | Public URL | Notes |
|---------|--------------|------------|-------|
| ollama | 11434 | — | GPU, RTX 2080 Ti |
| openwebui | 8282→8080 | ai.paccoco.com (pending) | Postgres backend |
### Meshtastic
| Service | Internal Port | Public URL | Notes |
|---------|--------------|------------|-------|
| meshmonitor | 8081→3001 | meshmonitor.paccoco.com | Postgres backend |
| meshmonitor virtual node | 4404 | — | TCP virtual node server |
| meshmonitor-tileserver | 8082→8080 | — | Map tiles |
| meshmonitor-mqtt-proxy | — | — | MQTT→TCP bridge |
---
## Serenity
### Media Ingestion
| Service | Notes |
|---------|-------|
| sonarr | TV |
| sonarr-anime | Anime |
| radarr | Movies |
| lidarr | Music |
| readarr | Books |
| readarr-epub | EPUBs |
| prowlarr | Indexer manager |
| bazarr | Subtitles |
| unpackerr | Archive extraction |
| qBittorrent | Download client |
| GluetunVPN | VPN tunnel for qbit |
| autobrr | Auto-grab |
| qbit_manage | qBit maintenance |
| Notifiarr | Notifications |
| Wizarr | User invites |
| romm | ROM manager |
| GameVault | Game library |
| shelfmark | Book/audiobook search, port 8084 |
---
## N.O.M.A.D.
## Shared Databases (PD)
| Service | Port | Notes |
|---------|------|-------|
| Pelican Panel | 80/443 | panel.paccoco.com, PHP 8.4 + nginx + MariaDB |
| Wings | 8443 | node1.paccoco.com, game server daemon |
| Minecraft | 25565 | Purpur, Java 21, direct port forward |
| N.O.M.A.D. containers | — | 10 containers, start_nomad.sh / stop_nomad.sh |
| PostgreSQL | 5432 | Shared across stacks via `ix-databases_shared-databases` network |
| MariaDB | 3306 | Shared across stacks |
| Redis | 6379 | Shared across stacks |
## Infrastructure (PD)
| Service | Port | URL | Status |
|---------|------|-----|--------|
| Homepage | 3300 | http://pd:3300 | ✅ Active |
| Dockhand | 3230 | http://pd:3230 | ✅ Active |
| Uptime Kuma | 3001 | http://pd:3001 | ✅ Active |
| Gotify | 8443 | https://pd:8443 | ✅ Active |
| Gitea | 3002 / 2222 | http://pd:3002 (SSH: 2222) | ✅ Active |
| Shlink | 8087 | http://pd:8087 | ✅ Active |
| Shlink Web Client | 8088 | http://pd:8088 | ✅ Active |
| RackPeek | 8283 | http://pd:8283 | ✅ Active |
## AI Stack
| Service | Host | Port | Status |
|---------|------|------|--------|
| LiteLLM | PD | 4000 | ✅ Active |
| OpenWebUI | PD | 8282 | ✅ Active |
| Qdrant | PD | 6333 (HTTP) / 6334 (gRPC) | ✅ Active |
| Whisper (faster-whisper) | PD | 8786 | ✅ Active |
| SearXNG | PD | 8888 | ✅ Active |
| Ollama — light tier | N.O.M.A.D. (10.5.1.16) | 11434 | ✅ Active |
| Ollama — heavy tier | Rocinante (10.5.1.112) | 11434 | ✅ Active |
| Reranker (TEI) | Serenity (10.5.1.5) | 9787 | ✅ Active |
## Media (PD)
| Service | Port | Status |
|---------|------|--------|
| Plex | 32400 | ✅ Active |
| Tautulli | 8181 | ✅ Active |
| Audiobookshelf | 13358 | ✅ Active |
| Calibre-Web | 8183 | ✅ Active |
| Seerr (Overseerr) | 5055 | ✅ Active |
## Productivity / Home (PD)
| Service | Port | Status |
|---------|------|--------|
| Immich | 2283 | ✅ Active |
| Paperless-NGX | 8083 | ✅ Active |
| Karakeep | 3100 | ✅ Active |
| n8n | 5678 | ✅ Active |
| KitchenOwl | 8086 | ✅ Active |
| DoneTick | 2021 | ✅ Active |
| Dakboard Bridge | 5087 | ✅ Active |
| Qui | 7476 | ✅ Active |
## Smart Home (PD)
| Service | Port | Status |
|---------|------|--------|
| Home Assistant | 8123 | ✅ Active |
| Kima Hub | 3333 | ✅ Active |
## Monitoring (PD)
| Service | Port | Status |
|---------|------|--------|
| Grafana | 3000 | ✅ Active |
| Prometheus | 9090 | ✅ Active |
| MeshMonitor | 8081 | ✅ Active |
## Mapping / Geo (PD)
| Service | Port | Status |
|---------|------|--------|
| TileServer GL | 8082 | ✅ Active |
## Game Servers (N.O.M.A.D. — 10.5.1.16)
| Service | Notes |
|---------|-------|
| Pelican / Wings | Game server management panel |
| Minecraft | Managed via Pelican |