Overview
A fully automated, self-healing homelab media stack built on Docker Compose. Handles everything from media requests to downloading, extracting, renaming, subtitle fetching, quality management, and streaming — with zero manual intervention after initial setup. All download traffic routes through a WireGuard VPN with a firewall kill switch. A custom cascade-restart monitor automatically recovers all dependent services when the VPN restarts. Container image updates are detected daily and applied automatically with push notifications at each step. The stack is split into three independent Docker Compose projects sharing a common bridge network. This allows each stack to be updated, restarted, or debugged in isolation. Twenty-plus services are orchestrated across three network zones: the Gluetun VPN namespace, a shared bridge network, and the host network for Plex.
Tech Stack
Key Features
- All download traffic routed through ProtonVPN WireGuard with firewall kill switch — no leaks if VPN drops
- gluetun-monitor cascade restart: detects Gluetun namespace changes, waits for healthy status, stops and recreates all 9 VPN-dependent services with exponential backoff retries
- Rate limiting on cascade restarts (max 5/hr) with loop detection and 1-hour pause
- Daily container image updates via What's Up Docker + Python webhook server — zero manual intervention
- Push notifications via ntfy.sh at every automation stage (updates, restarts, failures)
- Hardlink-based media import — file exists in two paths, occupies disk space once, seeding continues uninterrupted
- Recyclarr syncs TRaSH Guides quality profiles and custom formats to Sonarr/Radarr on a schedule
- cross-seed daemon matches completed downloads against other indexers for zero-bandwidth ratio boosting
- Three self-healing layers: Docker healthchecks → Autoheal watchdog → gluetun-monitor cascade restart
- Maintainerr rules automatically remove stale media from Plex based on watch history thresholds
- SuggestArr sends AI-powered media recommendations back into Seerr automatically
- VPN port forwarding auto-updates qBittorrent listening port on each VPN session via Gluetun API commands
- stack-manage.sh wraps all docker compose operations per stack with a clean CLI interface
- Timestamped config backups excluding media files for fast disaster recovery
Architecture
Three-Stack Architecture
The system is split into three independent Docker Compose projects sharing a common bridge network (homelab_media_network). Each stack can be updated or restarted without affecting the others.
Network Topology
Three distinct network zones enforce traffic isolation. All torrent services share the Gluetun VPN namespace and communicate via localhost. No traffic leaves without passing through WireGuard.
VPN Auto-Healing Flow
When Gluetun restarts it creates a new network namespace, orphaning all dependent containers. gluetun-monitor detects this via SandboxKey comparison, waits up to 300s for Gluetun to become healthy, then stops and recreates all 9 VPN-dependent services with retry logic and rate limiting.
Media Request Pipeline
End-to-end flow from a user request to media appearing in Plex, fully automated across seven services.
Container Auto-Update Pipeline
What's Up Docker checks all image tags daily at 06:00. Updates trigger a webhook to a Python server which pulls the new image and recreates the container. Success and failure are reported via push notification.