homelab-blueprint/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
BentoPDF	Privacy-first client-side PDF toolkit
Beszel Agent	Host and Docker monitoring agent
Beszel Hub	Beszel monitoring dashboard
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
IT-Tools	Developer and sysadmin utility toolbox
Koffan	Shared household grocery/shopping list
Paperless-ngx	Document management with OCR and full-text search
PostgreSQL	PostgreSQL and pgAdmin
Rackula	Drag-and-drop server rack layout designer
SnapOtter	Offline file toolkit (image, video, audio, PDF)
Technitium DNS	DNS server and ad blocking
Youtarr	YouTube downloader with metadata and media-server integrations

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

See the documentation index for all guides. Most-used:

• Arr Stack storage deployment
• Troubleshooting
• UniFi custom firewall rules