# Homelab Architecture Overview

## Primary Docker Host
Host: `PlausibleDeniability` (TrueNAS Scale)

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

## 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`

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

## Storage Model

### 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

Notable appdata on SSD:
- plex, tautulli, audiobookshelf, seerr, dockhand, rackpeek
- immich, immich-ml, ollama, openwebui
- shlink, gitea, netdata, tailscale, uptime-kuma

### TrueNAS Pool (tank)
Mounted at: `/mnt/tank`
- General appdata: `/mnt/tank/docker/appdata/`
- Backups: `/mnt/tank/docker/backups/`
- Downloads: `/mnt/tank/docker/downloads/`

Notable appdata on tank:
- homepage, newt, dockhand (config only)
- kitchenowl, donetick, qui
- calibre-web-automated config

### Unraid NFS
Mounted at: `/mnt/unraid`
- Media libraries: `/mnt/unraid/data/media/`
- Immich media: `/mnt/unraid/immich`

## 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

## Active Stacks (as of 2026-05-05)

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

### 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