TrueNAS Home Lab Apps¶
Docker Compose stacks for a TrueNAS home lab server, managed with SOPS, Renovate, and GitOps.
Overview¶
Each app lives under services/ with its own compose.yaml, environment files, and SOPS-encrypted
secrets. A cron-driven continuous deployment script pulls changes from this repo and redeploys apps
automatically — on TrueNAS and a handful of VMs (see servers.yaml).
The setup follows Techno Tim's guide on running Docker on TrueNAS like a pro.
Benefits¶
- GitOps without Kubernetes — Git-driven, automated deployments without the operational overhead of running a Kubernetes cluster. Compose definitions stay in git, not buried in the TrueNAS UI.
- Secrets & automated updates — SOPS + Age encrypts secrets at rest; Renovate automatically opens PRs for new image digests, keeping maintenance low.
- TrueNAS-native storage — Containers bind-mount ZFS datasets directly — no NFS in the data path, avoiding latency and corruption risks for stateful apps like databases. Each app gets its own dataset for independent snapshots and rollback.
- 3-2-1 backups — ZFS snapshots, cross-pool replication, and encrypted off-site sync to Azure Blob Storage. See Backup Strategy.
- Managed platform — TrueNAS maintains the host OS and provides built-in container views, removing the need to manage the underlying system or add extra monitoring tooling.
- Flexibility — Standard Docker Compose means the setup works with tools like Portainer or Dockge without significant rework.
Apps¶
| App | Purpose |
|---|---|
| AdGuard Home | DNS filtering and ad blocking with Unbound resolver |
| Alloy | Telemetry collector — host metrics, container metrics, logs |
| Bazarr | Subtitle manager for Sonarr and Radarr |
| Bitwarden Lite | Self-hosted password manager (SQLite-backed, single container) |
| changedetection.io | Website change monitoring with browser fetching and notifications |
| Cloudflared | Cloudflare Tunnel agent for exposing services via edge network |
| Dawarich | Self-hosted location history and GPS tracking |
| Dozzle | Real-time container log viewer |
| Draw.io | Flowchart and diagram maker |
| Echo Server | HTTP echo server for testing Traefik routing |
| ESPHome | ESP device management and firmware builder |
| Excalidraw | Virtual whiteboard for hand-drawn diagrams |
| Frigate | NVR with real-time AI object detection |
| Gatus | Uptime monitoring with alerting and a status page |
| Home Assistant | Open source home automation platform |
| Homepage | Customizable dashboard for home lab services |
| Immich | Self-hosted photo and video management |
| Karakeep | Bookmark manager for links, notes, images, and full-text search |
| Lidarr | Music collection manager and download automation |
| Matter Server | Matter/Thread smart home device bridge |
| Memos | Private note-taking and knowledge service |
| MeTube | YouTube downloader via yt-dlp with a web UI |
| Mosquitto | MQTT broker for IoT device communication |
| Open Archiver | Encrypted email archive with search/OCR — blocked candidate; adoption approval and reviewed activation required |
| OpenClaw | Self-hosted personal AI assistant and gateway |
| Outline | Knowledge base and wiki with Azure AD authentication |
| Plex | Media server with hardware transcoding |
| Prowlarr | Indexer manager for the arr stack |
| qBittorrent | BitTorrent client with web interface |
| Radarr | Movie collection manager and download automation |
| SABnzbd | Usenet download client |
| Sonarr | TV series collection manager and download automation |
| Spottarr | Spotnet Usenet indexer |
| SQLite Web | SQLite database browser for Home Assistant |
| Traefik | Reverse proxy with automatic SSL via Cloudflare DNS |
| Traefik Forward Auth | SSO authentication via Microsoft Entra ID |
| TubeSync | YouTube channel and playlist synchronisation |
| Unifi | Ubiquiti network controller with MongoDB backend |
| wmbusmeters | Wireless M-Bus smart meter reader (water/gas/heat) |
Open Archiver is listed as a candidate, not a running service. Do not provision
its listed dataset or create its Custom App until the
activation prerequisites
are complete, including image/runtime clearance, the approved image pin,
and the administrator-only Entra app-role assignment. Follow the existing
app-first sequence: dccd-app open-archiver, preparation, then Custom App
creation. Let the Custom App create its network before applying the reviewed,
tracked Traefik network entries and running the final dccd-all. Coordinate
scheduled redeploys to prevent Traefik from referencing a missing network.
The enrollment guard applies only to TrueNAS-mode dccd. Raw Compose and generic/unscoped deployment outside TrueNAS mode can start this stack before its Custom App exists; do not use those paths before the activation prerequisites are complete.
Personal Home Folders¶
Personal Home Folders documents the approved native TrueNAS 25.10 setup for persistent, non-admin SSH homes and private SMB personal files. This is an operator guide, not a Docker app or GitOps deployment; host configuration and access/backup tests remain pending.
vm-pool/homes # One shared Multiprotocol/NFSv4/Passthrough dataset
<username>/ # Ordinary home directory created by TrueNAS
<username> is a placeholder. For each personal account, check Create Home
Directory and select the parent /mnt/vm-pool/homes; TrueNAS appends the
username and creates a private directory, not a per-user dataset. Separately
create its ordinary Files/ directory and private <username>-files SMB share.
.ssh, .config, and shell dotfiles remain SSH/local-only. The shared dataset
supports user quotas; snapshots cover all homes, so a rollback affects every user.
The homes dataset is a sibling of vm-pool/apps, outside the repository and
apps table. The existing truenas_admin home and boot-time mirror stay unchanged.
Dataset Layout¶
Create a nested dataset hierarchy for granular snapshot and backup control. Each app's Compose definition is tracked in Git; persistent data lives in its dataset. For registry-supported new apps, use the brand-new Custom App rollout to provision the account and dataset while preserving the checkout.
vm-pool/apps # root — holds the git repo
vm-pool/apps/services # parent for all app datasets
vm-pool/apps/services/adguard
vm-pool/apps/services/alloy
vm-pool/apps/services/bazarr
vm-pool/apps/services/bitwarden
vm-pool/apps/services/changedetection
vm-pool/apps/services/dawarich
vm-pool/apps/services/dozzle
vm-pool/apps/services/drawio
vm-pool/apps/services/echo-server
vm-pool/apps/services/esphome
vm-pool/apps/services/frigate
vm-pool/apps/services/gatus
vm-pool/apps/services/home-assistant
vm-pool/apps/services/homepage
vm-pool/apps/services/immich
vm-pool/apps/services/karakeep
vm-pool/apps/services/lidarr
vm-pool/apps/services/matter-server
vm-pool/apps/services/memos
vm-pool/apps/services/metube
vm-pool/apps/services/mosquitto
vm-pool/apps/services/open-archiver
vm-pool/apps/services/openclaw
vm-pool/apps/services/outline
vm-pool/apps/services/plex
vm-pool/apps/services/prowlarr
vm-pool/apps/services/qbittorrent
vm-pool/apps/services/radarr
vm-pool/apps/services/sabnzbd
vm-pool/apps/services/sonarr
vm-pool/apps/services/spottarr
vm-pool/apps/services/sqlite-web
vm-pool/apps/services/traefik
vm-pool/apps/services/traefik-forward-auth
vm-pool/apps/services/tubesync
vm-pool/apps/services/unifi
vm-pool/apps/services/wmbusmeters
# ... one dataset per app
Documentation¶
| Page | Description |
|---|---|
| Architecture | Compose patterns, container security, networking |
| Infrastructure | UID/GID allocation, storage, multi-server deployment |
| Contributing | Renovate, commit conventions, release process |
| Database Upgrades | PostgreSQL major version upgrade procedures |
| Disaster Recovery | Full rebuild procedures for a fresh TrueNAS |
| Home Folders | Native private SMB folders and persistent SSH homes |
| Troubleshooting | Docker, DNS, and permissions diagnostics |
| Retired Services | Log of retired services and last active state |
Development¶
This repo uses go-task as a task runner (managed by mise). List all available commands:
Common workflows:
task test # Run the BATS test suite (unit + integration)
task lint # Run all linters
task format # Auto-format all files
task ci:local # Run the full CI pipeline locally
See Contributing for testing details, commit conventions, and the release process.