Homelab Media Stack
Fully automated, self-healing Docker media stack with VPN kill switch, cascade restart recovery, and zero-touch container updates.
01 Overview
A fully automated, self-healing homelab media stack built on Docker Compose. It covers the full pipeline: media requests, downloading, extracting, renaming, subtitle fetching, quality management, and streaming, with no 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.
02 Key Features
03 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.