truenas-stacks/docs/architecture/ARCHITECTURE_OVERVIEW.md

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