brianpooe/homelab-blueprint
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
No description
260 commits 1 branch 0 tags 1.6 MiB
Find a file
Brian Pooe bba03c675a Fix arr-stack OOM kills and decluttarr auth for 25 GB downloads 
- qbittorrent memory limit 1G → 3G: piece-verification buffers for 25 GB+
  torrents exceed 1G and trigger cgroup OOM kill mid-download
- bazarr, prowlarr, seerr limits 512M → 1G: all three were at 40-67% at
  idle with insufficient headroom for subtitle batch events, RSS floods,
  and Emby library syncs respectively
- Add *media-data-mount and storage-guard dependency to decluttarr so
  detect_deletions can access /data/media paths
- Fix decluttarr auth ban loop: add Docker bridge 172.18.0.0/16 to
  qBittorrent WebUI auth subnet whitelist (applied live via API)
- Update README mount table (Decluttarr now gets /data/media), memory
  limit table with per-service rationale sized for 25 GB average files
- Add TROUBLESHOOTING sections 5e-5j covering qBittorrent path issues,
  OOM kill pattern, and decluttarr auth ban loop with fixes

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-21 17:52:19 +02:00
docker-compose-files Fix arr-stack OOM kills and decluttarr auth for 25 GB downloads 2026-06-21 17:52:19 +02:00
docs Fix arr-stack OOM kills and decluttarr auth for 25 GB downloads 2026-06-21 17:52:19 +02:00
.env.sample Document persistent NFS mounts for all six UNAS Pro shares and point DOCKERSTORAGEDIR at arr_data 2026-06-20 11:51:15 +02:00
.gitignore Feature-slice Caddy configuration 2026-06-13 17:47:19 +02:00
ipfconfig Add Makefile and unify stack management 2026-06-17 18:57:05 +02:00
Makefile Harden strict substitution workflow 2026-06-17 22:15:54 +02:00
README.md Harden strict substitution workflow 2026-06-17 22:15:54 +02:00
setup-homeassistant.sh Refactor environment management into modular, stack-specific files 2026-06-17 21:42:48 +02:00
substitute_env.sh Harden strict substitution workflow 2026-06-17 22:15:54 +02:00

README.md

Homelab Blueprint

Docker Compose templates and deployment guides for self-hosted services.

Quick Start

  1. Copy the sample environment file: 
    cp -n .env.sample .env
  2. Configure .env with your values.
  3. Use the Makefile to deploy a stack: 
    make help            # See all available commands
make check-env       # Validate your .env file
make deploy-caddy    # Deploy the reverse proxy

Each stack guide in docker-compose-files/<stack>/README.md explains appdata placement, rendering, and networking.

Stacks

Stack Description
Arr Stack Media management, downloads, VPN, Emby, and Recyclarr
Beszel Agent Host and Docker monitoring agent
Beszel Socket Proxy Restricted Docker API access for Beszel
Caddy Reverse proxy with Cloudflare DNS-01
Gramps Web Genealogy web application
Home Assistant Home Assistant, Mosquitto, and Zigbee2MQTT
Immich Photo and video management with GPU acceleration
PostgreSQL PostgreSQL and pgAdmin
Technitium DNS DNS server and ad blocking
Vault HashiCorp Vault secrets management

Management

The repository includes a Makefile to unify management of all stacks. It supports modular environment files, loading variables first from the root .env (Global) and then from the stack's own .env (Local).

Command Description
make check-env Validates root and stack .env files against required placeholders in renderable templates
make status Shows docker compose ps for all generated compose files
make reload-caddy Zero-downtime reload of the Caddy configuration
make ip-check Verifies VPN connectivity for Arr Stack containers
make deploy-<stack> Renders templates and starts the specified stack

Custom Services (Rust/MQTT)

To add your own services (e.g., Rust-based backends):

  1. Add your service to a new or existing docker-compose.*.yml.
  2. Connect it to the ha-network if it needs to reach Home Assistant.
  3. Expose it via Caddy by adding a block to docker-compose-files/caddy/Caddyfile_template and running make deploy-caddy.

Shared Commands

Most stacks use the following manual pattern (automated by make):

./substitute_env.sh docker-compose-files/<stack>/template.yaml docker-compose.<stack>.yml .env
docker compose -f docker-compose.<stack>.yml config --quiet
docker compose -f docker-compose.<stack>.yml up -d

Home Assistant uses its setup script instead. Arr Stack, Caddy, and Gramps Web render additional configuration templates.

substitute_env.sh only reads env files passed on the command line. It does not fall back to OS environment variables or an implicit .env.

Requirements

  • Linux host with Docker Engine and Docker Compose
  • Git
  • A configured .env based on .env.sample
  • Service-specific storage and network access described in each stack README

Generated docker-compose.*.yml files may contain secrets and are ignored by Git.

Operational Documentation