Comprehensive overview of the two-tier homelab infrastructure architecture, designed for modularity, security, and comprehensive monitoring with Git submodule-based management.
- Modularity: Each host managed as independent Git repository
- Orchestration: Central control through Ansible playbooks
- Monitoring: Comprehensive observability with Beszel, osquery, and Seq
- Security: Zero-trust networking with Tailscale and SSH key management
- Documentation: Automated wiki synchronization and centralized knowledge
- Infrastructure as Code: All configurations in version control
- Immutable Infrastructure: Containers and declarative configuration
- GitOps Workflow: Git → PR → Ansible CI/CD pipeline
- Family-Friendly: Technology that enhances family life
- Self-Hosted First: Minimize external dependencies
Purpose: Cross-system coordination and infrastructure-wide management
homelab-infrastructure/
├── ansible/ # Orchestration and task queue system
├── servers/ # Server submodules (lucille4-5, nas02, loose-seal)
├── workstations/ # Workstation submodules (family-macbook, matthews-macbook-air)
├── services/ # Service repositories (wiki, n8n-workflows, homeassistant-config, mcp-config)
├── shared/ # Shared utilities (python-utils)
├── dotfiles/ # Personal dotfiles with SOPS-encrypted secrets
├── scripts/ # Infrastructure scripts and automation
├── docs/ # Central documentation
├── templates/ # Templates for new hosts
└── .github/workflows/ # GitHub Actions for automation and CI/CD
Responsibilities:
- Cross-system coordination
- Infrastructure-wide deployments
- Resource scheduling and policy implementation
- Central monitoring and logging aggregation
- Backup orchestration and disaster recovery
- Security policy enforcement
- Configuration drift detection and remediation
Purpose: Local optimization and service management
Active Servers:
- lucille4: Production core services (Documents, Identity, AI, Workflows)
- lucille5: Development and testing workstation
- nas02: Media management, NVR, storage with Caddy proxy
- loose-seal: Monitoring and dashboards
- homeassistant: Home automation hub (Green device)
Decommissioned:
- lucille3: Archived 2025-07-05, replaced by Bambu Lab P1S 3D printer
Responsibilities:
- Local service optimization
- Host-specific configurations
- Performance tuning and resource management
- Service health monitoring
- Local backup execution
Primary connectivity layer providing zero-trust networking
Internet
↓
┌─────────────────────────────────────────────────────────────┐
│ Tailscale Mesh │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ lucille4 │ │ lucille5 │ │ nas02 │ │
│ │100.92.167.33│ │100.83.87.19 │ │100.92.167.34│ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ loose-seal │ │homeassistant│ │family-macbook│ │
│ │100.79.102.97│ │100.79.102.110│ │100.83.87.20 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
↓
Local Networks (192.168.x.x)
Benefits:
- Automatic certificate management
- Cross-site connectivity
- Zero-configuration VPN
- Secure remote access
- MagicDNS for easy addressing
- Tailscale MagicDNS:
hostname.speicher.family
- Local DNS:
*.speicher.family (internal services)
- External DNS:
*.dratspiker.com (public services)
- Service Discovery: Automatic via Tailscale and local DNS
- Caddy: Automatic HTTPS with Let's Encrypt
- Internal TLS: Tailscale certificates
- Certificate Rotation: Automated renewal
- HSTS: HTTP Strict Transport Security enabled
Role: Critical business and family services
Service Categories:
- Identity & Auth: Authentik SSO, user management
- Documents: Paperless-ngx document management
- AI & ML: Ollama LLM, ComfyUI, Open WebUI
- Development: Code-Server, Jupyter Hub, pgAdmin
- Automation: n8n workflows, MCP servers
- Knowledge: Recipe management (Mealie), bookmarks (Karakeep)
Characteristics:
- 24/7 uptime requirement
- High availability configurations
- Regular automated backups
- Performance monitoring
- Security hardening
Role: Media services and bulk storage
Service Categories:
- Media Streaming: Jellyfin media server
- Media Acquisition: Sonarr, Radarr, Jellyseerr
- Security: Frigate NVR with AI detection
- Storage: 12TB RAID array for media
- Proxy: Caddy reverse proxy for all services
Characteristics:
- High storage capacity
- Optimized for media workloads
- Hardware transcoding support
- Automated content management
- Network storage integration
Role: Observability and system monitoring
Service Categories:
- Metrics: Beszel system monitoring
- Logging: Seq log aggregation and analysis
- Dashboards: Grafana visualization
- Alerting: Notification and alert management
Characteristics:
- Centralized monitoring data
- High-performance storage for logs
- Real-time alerting capabilities
- Historical data retention
- Cross-system visibility
Role: Smart home automation hub
Service Categories:
- Device Control: Smart home device management
- Automation: Home automation routines
- Integration: IoT device connectivity
- Voice Control: Local voice processing
Characteristics:
- Dedicated IoT device
- Real-time responsiveness
- Local processing priority
- Integration with homelab services
- Family-friendly interface
graph TB
HA[Home Assistant] --> Frigate[Frigate NVR]
HA --> n8n[n8n Workflows]
Authentik --> Paperless[Paperless-ngx]
Authentik --> Mealie
Authentik --> Grafana
Jellyfin --> Jellyseerr
Jellyseerr --> Sonarr
Jellyseerr --> Radarr
n8n --> Ollama[Ollama LLM]
n8n --> HA
n8n --> External[External APIs]
Beszel --> Seq[Seq Logging]
Frigate --> HA
All --> Caddy[Caddy Proxy]
Caddy --> Internet
- User Request → Caddy Proxy
- Authentication Check → Authentik SSO
- User Validation → Service Access
- Service Response → User Interface
- Service Metrics → Beszel Hub
- Application Logs → Seq Aggregation
- System Events → Centralized Dashboard
- Alerts → Notification Services
- Tailscale VPN: Encrypted mesh networking
- Firewall Rules: Host-based firewalls
- Network Segmentation: Service isolation
- Zero Trust: No implicit trust assumptions
- SSO: Centralized authentication via Authentik
- MFA: Multi-factor authentication support
- Role-Based Access: Granular permissions
- Session Management: Secure session handling
- SOPS Encryption: Age-encrypted secrets
- 1Password Integration: Backup key storage
- Environment Isolation: Service-specific secrets
- Rotation Policies: Regular secret updates
- Container Isolation: Docker security boundaries
- Regular Updates: Automated security patching
- Vulnerability Scanning: Continuous security monitoring
- Audit Logging: Comprehensive activity tracking
- Load Balancing: Caddy-based load distribution
- Service Replication: Multi-instance deployments
- Database Clustering: Planned PostgreSQL clustering
- Storage Expansion: Additional NAS integration
- Resource Monitoring: Real-time usage tracking
- Performance Optimization: Service-specific tuning
- Hardware Upgrades: Planned capacity increases
- Bottleneck Identification: Proactive monitoring
- Kubernetes Migration: Planned container orchestration
- Edge Computing: IoT device integration
- Multi-Site: Geographic distribution
- Disaster Recovery: Off-site replication
Developer → Git Commit → GitHub PR → Automated Tests → Merge → Ansible Deploy
↓ ↓
Validation Checks Production Update
Security Scans Health Verification
Configuration Tests Rollback Capability
- Code Changes: Git commits to feature branches
- Pull Request: Automated validation and testing
- Merge Approval: Human review and approval
- Staging Deploy: Automated deployment to lucille5
- Production Deploy: Manual approval for production
- Health Checks: Automated verification and monitoring
- Ansible Playbooks: Declarative infrastructure configuration
- Git Submodules: Modular host management
- Environment Separation: Dev/staging/production isolation
- Drift Detection: Automated configuration compliance
- Service Health: Application-specific health checks
- Performance Metrics: Response times and throughput
- Error Tracking: Application error monitoring
- User Experience: End-user performance monitoring
- System Metrics: CPU, memory, disk, network
- Container Health: Docker container monitoring
- Service Discovery: Automatic service detection
- Resource Utilization: Capacity planning data
- Family Usage: Service adoption and usage patterns
- Cost Tracking: Infrastructure cost analysis
- Security Events: Security incident monitoring
- Compliance: Policy compliance verification
- Beszel: Real-time system metrics and dashboards
- Seq: Structured logging and log analysis
- Grafana: Custom dashboards and visualization
- Home Assistant: IoT device monitoring integration