TheMerinoWolf's Homelab

This Ansible project configures a Debian-based Proxmox homelab with:

• Hardened Debian OS with automatic security updates
• Secure remote access via Cloudflare tunnels
• DNS filtering with AdGuard Home, using upstream CloudFlare Secure Web Gateway DNS servers (including malware blocking)
• Recipe management with Mealie
• AI chat interface with Open WebUI
• Weekend hiking weather forecasting with custom Flask app
• Customizable dashboard via Homepage
• Reverse proxying with automatic TLS using Caddy
• Centralized metrics/logging using Grafana Alloy (free-tier Grafana Cloud)
• Synthetic monitoring with Grafana Cloud private probes for uptime monitoring
• Zero public attack surface (no exposed ports, no public DNS entries)

Why Proxmox?

• Supports both containerized and full-OS services easily.
• Significantly simpler than Kubernetes or Docker swarm for small clusters or single-node setups.
• Built-in robust backup and snapshot management.

For more details, see Why Proxmox?

Quick Start

1. Clone this repository:

   git clone https://github.com/TheMerinoWolf/homelab-infra.git
   cd homelab-infra
   make setup    # Install all dependencies
   make help     # See all available targets

2. Configure your deployment:

   • Copy inventory/hosts.example to inventory/hosts and update with your server details
   • Copy group_vars/homelab_secrets.yml.example to group_vars/homelab_secrets.yml and fill in your secrets
   • Follow the documentation:
     • Prerequisites
     • Python Setup
     • Initial Server Setup
     • Secrets Setup
     • Maintenance

3. Additional documentation:

   • Home Network Design
   • Mealie Backup System
   • Python Linting

Project Structure

The project follows Ansible best practices with a layered architecture organized by function:

• Infrastructure Layer: Base system configuration, runtimes, and core services
• Network Layer: Connectivity, routing, and reverse proxy services
• Security Layer: DNS filtering and security-related services
• Application Layer: User-facing applications and services
• Monitoring Layer: Observability, metrics, and logging

.
├── config/                   # Tool configuration files
│   ├── ansible-lint.yml      # Ansible lint configuration
│   └── yamllint.yml          # YAML lint configuration
├── docs/                     # Documentation
│   ├── home-network-design.md # Home network design and setup
│   ├── initial-setup.md      # Initial server setup guide
│   ├── maintenance.md        # Maintenance and troubleshooting guide
│   ├── mealie-backup.md      # Mealie backup system documentation
│   ├── prerequisites.md      # Prerequisites guide
│   ├── python-linting.md     # Python linting setup and configuration
│   ├── python-setup.md       # Python setup guide
│   ├── secrets-setup.md      # Secrets configuration guide
│   └── why-proxmox.md        # Proxmox selection rationale and benefits
├── group_vars/               # Group variables
│   ├── homelab_secrets.yml   # Encrypted secrets (vault)
│   └── homelab.yml           # Non-sensitive variables
├── inventory/                # Inventory files
│   └── hosts                 # Server inventory
├── playbooks/                # Focused operational playbooks
│   ├── bootstrap.yml         # Initial server setup playbook
│   ├── infrastructure.yml    # Infrastructure layer setup
│   ├── network.yml           # Network layer setup
│   ├── security.yml          # Security layer setup
│   ├── applications.yml      # Application layer setup
│   └── monitoring.yml        # Monitoring layer setup (metrics, logs, synthetic monitoring)
├── roles/                    # Ansible roles organized by function
│   ├── infrastructure/       # Infrastructure layer
│   │   ├── common/           # Common system configuration
│   │   ├── docker/           # Docker installation and setup
│   │   ├── golang/           # Go installation for services
│   │   ├── ntp/              # Network Time Protocol
│   │   └── rclone/           # Cloud storage tool for backups
│   ├── network/              # Network layer
│   │   ├── caddy/            # Caddy reverse proxy
│   │   └── cloudflared/      # Cloudflare tunnel setup
│   ├── security/             # Security layer
│   │   └── adguard/          # AdGuard Home DNS filtering
│   ├── applications/         # Application layer
│   │   ├── hiking_weather/   # Weekend hiking weather forecasting
│   │   ├── homepage/         # Homepage dashboard
│   │   ├── mealie/           # Mealie recipe manager with R2 backups
│   │   └── openwebui/        # Open WebUI AI chat interface
│   └── monitoring/           # Monitoring layer
│       ├── grafana_alloy/    # Grafana Alloy metrics and logs collection
│       └── synthetic_monitoring/ # Grafana Cloud synthetic monitoring
├── scripts/                  # Helper scripts
│   ├── get-vault-pass.sh     # Vault password script
│   └── grafana-logs-query-agent.py  # Grafana logs query agent
├── .cursorignore             # Cursor IDE ignore patterns
├── .gitignore                # Git ignore patterns
├── Makefile                  # Build automation and common tasks
├── pyproject.toml            # Python project configuration and 
└── site.yml                  # Main ansible playbook