Self-Hosted Homelab Infrastructure - Containerized Network Isolation & Security Architecture

Situation

Building a self-hosted homelab infrastructure required a security-first approach to network isolation while enabling external access and service-to-service communication. Traditional approaches of running all services on a single network created security risks: a compromised service could potentially access other services, and there was no clear security boundary between different service categories (homelab services, media services, network management).

The challenge was to implement containerized infrastructure using Docker Compose that would enforce security boundaries between service categories while still enabling necessary communication. Services needed automatic service discovery, SSL/TLS automation, and secure external access without port forwarding. Additionally, the infrastructure needed to be version-controlled for replicability, handle persistent data across container restarts, and support dynamic service addition without manual configuration.

Specific challenges included: UniFi Controller needing to manage network devices while maintaining container isolation, automatic service discovery and SSL certificate management for dynamic services, securing external access without port forwarding, and managing persistent data with proper permissions.

Task

The goal was to engineer containerized homelab infrastructure using Docker Compose with security-first network isolation architecture. The solution needed to:

Implement separate Docker networks for different service categories to enforce security boundaries
Deploy nginx-proxy as reverse proxy connecting isolated networks while maintaining network segmentation
Deploy 15+ services across 4 Docker Compose stacks with automatic service discovery
Implement SSL/TLS automation via Let's Encrypt
Configure Cloudflare Tunnel for secure external access without port forwarding
Version-control all infrastructure in Git repository for replicability

Success criteria included: services within the same network can communicate directly, services on different networks cannot access each other, automatic service discovery via VIRTUAL_HOST environment variables, automatic SSL certificate provisioning and renewal, secure external access without port forwarding, and complete infrastructure replicability from Git repository.

Action

Security-First Network Isolation Architecture

Implemented separate Docker bridge networks per service category to enforce security boundaries:

homelab_home-net (172.18.0.0/16): For homelab services (Nextcloud, FreshRSS, Syncthing)
media_mediarr-net (172.21.0.0/16): For media services (Jellyfin, Sonarr, Radarr, Bazarr, Prowlarr)
unifi-internal (172.26.0.0/16): For UniFi Controller MongoDB communication (isolated)
unifi_macvlan: For UniFi Controller direct LAN access (192.168.8.206, static IP)

Network Isolation Strategy:

Services within the same network communicate directly (e.g., Nextcloud → MariaDB)
Services on different networks cannot access each other, preventing lateral movement
nginx-proxy connects to multiple networks as external networks, enabling routing while maintaining isolation
Cloudflare Tunnel provides external access, routing all traffic through nginx-proxy as single entry point

UniFi Controller Dual Networking

Implemented dual networking for UniFi Controller to balance device management with security:

unifi-internal Bridge Network: For MongoDB communication (isolated from other services)
unifi_macvlan Network: For direct LAN access (192.168.8.206, static IP) enabling device discovery and management
Result: Enables device discovery and management while maintaining database isolation from other services

Automatic Service Discovery and SSL Automation

Configured nginx-proxy with automatic service discovery and SSL certificate management:

Docker Socket Monitoring: nginx-proxy monitors Docker socket for container changes
VIRTUAL_HOST Environment Variable: Services declare VIRTUAL_HOST for automatic configuration
Automatic Nginx Configuration: nginx-proxy automatically generates nginx configuration based on VIRTUAL_HOST
Let's Encrypt Companion: Automatically provisions and renews SSL certificates based on LETSENCRYPT_HOST environment variable
Persistent SSL Certificates: SSL certificates stored in persistent volume surviving container restarts
Result: Dynamic service addition without manual nginx configuration, automatic SSL certificate management

Cloudflare Tunnel for Secure External Access

Implemented Cloudflare Tunnel for secure external access without port forwarding:

Outbound Connection: Creates outbound connection from server to Cloudflare network, eliminating need for port forwarding
DDoS Protection: All traffic routed through Cloudflare's network providing DDoS protection and SSL termination
DNS Integration: DNS records point to Cloudflare, eliminating dynamic IP issues
Automatic Reconnection: Cloudflare Tunnel configured as Docker service with automatic reconnection on failure
Single Entry Point: All external traffic routed through nginx-proxy, maintaining security boundaries

Persistent Data and Configuration Management

Implemented persistent volumes with proper security and organization:

Volume Pattern: ${DATA_PATH}/service-name pattern for all services
Encrypted Environment Files: Environment files stored encrypted with git-crypt
Runtime Secret Loading: Docker Compose uses env_file directive to load secrets at runtime
Permission Management: Volume permissions set via user directive or PUID/PGID environment variables
Health Checks: Ensure services ready before dependent services start
Log Rotation: Logging configured with rotation (max-size: 100m, max-file: 3) to prevent disk fill

Technical Implementation Details

Architecture Decisions:

Containerized infrastructure with Docker Compose
Security-first network isolation with separate Docker networks per service category
nginx-proxy as reverse proxy connecting isolated networks
Cloudflare Tunnel for secure external access
Automatic service discovery via Docker socket monitoring
SSL/TLS automation via Let's Encrypt
Version-controlled Docker Compose configurations in Git repository

Service Deployment:

4 Docker Compose stacks: homelab, media, nginx-proxy, unifi
15+ services deployed across isolated networks
Automatic service discovery via VIRTUAL_HOST environment variables
Health checks for all services ensuring readiness before routing

Observability/Operations:

Docker logging with rotation (max-size: 100m, max-file: 3) for all services
Health checks for service monitoring
nginx-proxy logs for access monitoring
Cloudflare Tunnel logs for external access monitoring

Result

Infrastructure as Code Achievement

4 Docker Compose stacks version-controlled in Git repository (homelab, media, nginx-proxy, unifi), enabling replicable infrastructure with 15+ services across isolated networks. The version-controlled approach enables complete infrastructure replication by cloning the repository and running docker-compose.

Network Isolation Success

3 isolated Docker networks (homelab_home-net, media_mediarr-net, unifi-internal) + 1 macvlan network enforce security boundaries, preventing compromised services from accessing other networks while enabling necessary communication. Services within the same network communicate directly, but services on different networks cannot, demonstrating defense-in-depth security architecture.

Service Discovery Automation Impact

Automatic service discovery via nginx-proxy eliminates manual nginx configuration, enabling dynamic service addition with VIRTUAL_HOST environment variables. This reduces maintenance overhead and enables rapid service deployment without configuration changes to the reverse proxy.

SSL/TLS Automation Excellence

Automatic certificate management via Let's Encrypt Companion integrated with nginx-proxy ensures SSL certificates are automatically provisioned and renewed. Certificates stored in persistent volume survive container restarts, ensuring continuous SSL/TLS protection without manual intervention.

Secure External Access Success

Cloudflare Tunnel provides secure external access without port forwarding, DDoS protection, and SSL termination, eliminating dynamic IP issues and firewall management complexity. The single entry point through nginx-proxy maintains security boundaries while enabling external access to services.

Technical Stack

Docker, Docker Compose, nginx-proxy, Let's Encrypt, Cloudflare Tunnel, git-crypt, UniFi Controller, Nextcloud, Jellyfin, Sonarr, Radarr, Bazarr, Prowlarr, Syncthing, FreshRSS

Conclusion

The Self-Hosted Homelab Infrastructure project demonstrates replicable & resilient systems engineering through containerized infrastructure with security-first network isolation. By implementing separate Docker networks per service category and using nginx-proxy as a reverse proxy connecting isolated networks, the project enforces security boundaries while enabling necessary communication. The holistic "full-stack" infrastructure view is evident in the integration of network isolation, service discovery, SSL automation, and secure external access. The security-first approach ensures defense-in-depth security architecture, while automatic service discovery and SSL automation reduce operational overhead. This infrastructure investment—doing it right the first time—eliminates technical debt and enables rapid service deployment, showcasing how containerized infrastructure can be architected for both security and operational efficiency. The version-controlled approach ensures complete infrastructure replicability, transforming homelab management from manual, error-prone processes into automated, secure, and replicable infrastructure.