← Back to all posts

Home Lab Foundations

1/15/2025•9 min read•Home Lab•By Kevin

Proxmox: The Ultimate Homelab Foundation - A Complete Infrastructure Guide

Introduction

In the world of homelab enthusiasts and IT professionals looking to build robust testing environments, choosing the right virtualization platform is crucial. While options like VMware vSphere, Hyper-V, and various cloud platforms exist, Proxmox Virtual Environment (Proxmox VE) has emerged as the gold standard for homelab deployments. This comprehensive guide explores why Proxmox excels as a homelab foundation and provides a detailed roadmap for building a production-ready infrastructure stack.

Why Proxmox is Perfect for Homelabs

1. Open Source Excellence Without Compromise

Proxmox VE is built on proven open-source technologies including Debian Linux, KVM hypervisor, and LXC containers. Unlike proprietary solutions that require expensive licensing, Proxmox offers enterprise-grade features completely free for homelab use. The optional subscription is purely for support and enterprise repositories, not functionality.

2. Unified Virtualization Platform

Proxmox elegantly bridges the gap between traditional virtual machines (KVM) and modern containerization (LXC). This dual approach allows you to run legacy applications in full VMs while leveraging lightweight containers for microservices and modern applications.

3. Enterprise Features in Your Homelab

  • High Availability Clustering: Build resilient multi-node clusters
  • Live Migration: Move VMs between hosts with zero downtime
  • Integrated Backup System: Automated backups with compression and encryption
  • Software-Defined Storage: Built-in Ceph integration for distributed storage
  • Advanced Networking: VLAN support, software-defined networking with Open vSwitch

4. Web-Based Management Excellence

The intuitive web interface eliminates the need for complex command-line operations for daily tasks, while still providing shell access for advanced configurations. The interface is responsive, modern, and provides real-time monitoring of all system resources.

5. Resource Efficiency

Proxmox's lightweight hypervisor overhead means more resources available for your workloads. LXC containers provide near-bare-metal performance while maintaining isolation, perfect for running multiple services efficiently.

Comprehensive Homelab Architecture

Our recommended setup creates a robust, monitoring-rich environment suitable for development, testing, and learning enterprise technologies.

Core Infrastructure Layer

Proxmox Host Requirements:

  • Minimum: 32GB RAM, 6-core CPU, 500GB NVMe SSD
  • Recommended: 64GB+ RAM, 8+ core CPU, 1TB+ NVMe + additional storage
  • Network: Gigabit Ethernet minimum, 10GbE preferred for storage traffic

VM/Container Allocation Strategy

Docker Host (VM)
├── CPU: 6 cores
├── RAM: 16GB
├── Storage: 200GB
└── OS: Ubuntu 22.04 LTS

Management Tools (LXC)
├── CPU: 2 cores  
├── RAM: 4GB
├── Storage: 50GB
└── Services: Semaphore, Terraform state

Monitoring Stack (VM)
├── CPU: 4 cores
├── RAM: 8GB  
├── Storage: 100GB
└── Services: InfluxDB, Grafana, Wazuh

TacticalRMM (VM)
├── CPU: 4 cores
├── RAM: 8GB
├── Storage: 100GB
└── OS: Ubuntu 22.04 LTS

Service Implementation Guide

1. Docker Foundation with Portainer

Docker serves as our containerization platform, with Portainer providing intuitive management.

Docker Host Setup:

# Update system
sudo apt update && sudo apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Deploy Portainer
docker volume create portainer_data
docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:latest

2. Automated Updates with Watchtower

Watchtower automatically updates your Docker containers, crucial for maintaining security.

services:
  watchtower:
    image: containrrr/watchtower
    container_name: watchtower
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_SCHEDULE=0 0 4 * * *  # 4 AM daily
      - WATCHTOWER_NOTIFICATIONS=slack
      - WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL=your_slack_webhook_url

3. Discord Integration for Notifications

Create a comprehensive notification system using Discord webhooks.

services:
  discord-notifier:
    image: notification-service:latest
    container_name: discord-notifier
    restart: always
    environment:
      - DISCORD_WEBHOOK=https://discord.com/api/webhooks/your_webhook_url
      - NOTIFICATION_LEVEL=INFO
    volumes:
      - ./logs:/app/logs

4. Security Monitoring with Wazuh

Wazuh provides SIEM capabilities, intrusion detection, and compliance monitoring.

services:
  wazuh.manager:
    image: wazuh/wazuh-manager:4.7.0
    container_name: wazuh.manager
    restart: always
    ports:
      - "1514:1514"
      - "1515:1515"
      - "514:514/udp"
      - "55000:55000"
    environment:
      - INDEXER_URL=https://wazuh.indexer:9200
      - INDEXER_USERNAME=admin
      - INDEXER_PASSWORD=SecretPassword
      - FILEBEAT_SSL_VERIFICATION_MODE=full
    volumes:
      - wazuh_api_configuration:/var/ossec/api/configuration
      - wazuh_etc:/var/ossec/etc
      - wazuh_logs:/var/ossec/logs
      - wazuh_queue:/var/ossec/queue
      - wazuh_var_multigroups:/var/ossec/var/multigroups
      - wazuh_integrations:/var/ossec/integrations
      - wazuh_active_response:/var/ossec/active-response/bin
      - wazuh_agentless:/var/ossec/agentless
      - wazuh_wodles:/var/ossec/wodles

  wazuh.indexer:
    image: wazuh/wazuh-indexer:4.7.0
    container_name: wazuh.indexer
    restart: always
    ports:
      - "9200:9200"
    environment:
      - "OPENSEARCH_JAVA_OPTS=-Xms1g -Xmx1g"
    ulimits:
      memlock:
        soft: -1
        hard: -1
      nofile:
        soft: 65536
        hard: 65536
    volumes:
      - wazuh-indexer-data:/var/lib/wazuh-indexer

  wazuh.dashboard:
    image: wazuh/wazuh-dashboard:4.7.0
    container_name: wazuh.dashboard
    restart: always
    ports:
      - 5601:5601
    environment:
      - INDEXER_USERNAME=admin
      - INDEXER_PASSWORD=SecretPassword
      - WAZUH_API_URL=https://wazuh.manager
      - DASHBOARD_USERNAME=kibanaserver
      - DASHBOARD_PASSWORD=kibanaserver
    depends_on:
      - wazuh.indexer
    links:
      - wazuh.indexer:wazuh.indexer
      - wazuh.manager:wazuh.manager

5. Monitoring Stack: InfluxDB + Grafana

Create a powerful monitoring solution for comprehensive infrastructure visibility.

services:
  influxdb:
    image: influxdb:2.7
    container_name: influxdb
    restart: always
    ports:
      - "8086:8086"
    environment:
      - DOCKER_INFLUXDB_INIT_MODE=setup
      - DOCKER_INFLUXDB_INIT_USERNAME=admin
      - DOCKER_INFLUXDB_INIT_PASSWORD=secretpassword
      - DOCKER_INFLUXDB_INIT_ORG=homelab
      - DOCKER_INFLUXDB_INIT_BUCKET=metrics
      - DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=your-super-secret-auth-token
    volumes:
      - influxdb-data:/var/lib/influxdb2
      - influxdb-config:/etc/influxdb2

  telegraf:
    image: telegraf:latest
    container_name: telegraf
    restart: always
    depends_on:
      - influxdb
    volumes:
      - ./telegraf.conf:/etc/telegraf/telegraf.conf:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /sys:/host/sys:ro
      - /proc:/host/proc:ro
      - /etc:/host/etc:ro
    environment:
      - HOST_ETC=/host/etc
      - HOST_PROC=/host/proc
      - HOST_SYS=/host/sys

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    restart: always
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
      - GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource
    volumes:
      - grafana-data:/var/lib/grafana
      - ./grafana/provisioning:/etc/grafana/provisioning
    depends_on:
      - influxdb

6. TacticalRMM for Endpoint Management

TacticalRMM is actually a swindle unless you're looking for an RMM that's essentially a mandatory paid product that has half the support of competing RMMs. I was quite dissapointed to find out only after setting up CNAME and A/SRV records on my DNS, building a docker compose with configs and volumes - that TacticalRMM requires a paid access plan / forced donation in order to use the code signing feature for the TacticalRMM agents. This is required for any MacOS or Linux agent deployment. There is supposedly a work around using your own cert to sign the agent during build, but they (I suspect intentionally) don't document any of it or the processs...at least well enough to instill confidence.

~~TacticalRMM~~ provides ~comprehensive~ remote monitoring and management capabilities.~ ~ Strikethrough ~ (Sorry supposed to be a strikethrough above showing my distain for TacticalRMMs practices...but may have to work on my MDX formatting implementation).

# Install TacticalRMM
wget https://raw.githubusercontent.com/amidaware/tacticalrmm/master/install.sh
chmod +x install.sh
sudo ./install.sh

# Follow the interactive installation process
# Configure your domain, email, and database settings

7. Infrastructure as Code with Ansible & Semaphore

Semaphore provides a modern web UI for Ansible automation.

services:
  semaphore:
    image: semaphoreui/semaphore:latest
    container_name: semaphore
    restart: always
    ports:
      - "3001:3000"
    environment:
      - SEMAPHORE_DB_DIALECT=postgres
      - SEMAPHORE_DB_HOST=postgres
      - SEMAPHORE_DB_PORT=5432
      - SEMAPHORE_DB_USER=semaphore
      - SEMAPHORE_DB_PASS=semaphore
      - SEMAPHORE_DB_NAME=semaphore
      - SEMAPHORE_PLAYBOOK_PATH=/tmp/semaphore/
      - SEMAPHORE_ADMIN_PASSWORD=changeme
      - SEMAPHORE_ADMIN_NAME=admin
      - SEMAPHORE_ADMIN_EMAIL=admin@localhost
      - SEMAPHORE_ADMIN=admin
      - SEMAPHORE_ACCESS_KEY_ENCRYPTION=gs72mPntFATGJs9qK0pQ0UI2E1oKXeoO
      - SEMAPHORE_LDAP_ACTIVATED=no
    depends_on:
      - postgres
    volumes:
      - semaphore-data:/etc/semaphore

  postgres:
    image: postgres:14
    container_name: semaphore-postgres
    restart: always
    environment:
      - POSTGRES_USER=semaphore
      - POSTGRES_PASSWORD=semaphore
      - POSTGRES_DB=semaphore
    volumes:
      - postgres-data:/var/lib/postgresql/data

8. Terraform for Infrastructure Management

Create a Terraform management container for infrastructure provisioning.

FROM hashicorp/terraform:latest

RUN apk add --no-cache \
    curl \
    jq \
    bash \
    openssh-client \
    git

WORKDIR /workspace

COPY terraform/ ./

CMD ["terraform", "--help"]

services:
  terraform:
    build: .
    container_name: terraform-runner
    volumes:
      - ./terraform:/workspace
      - terraform-state:/workspace/.terraform
      - ~/.ssh:/root/.ssh:ro
    environment:
      - TF_VAR_proxmox_host=${PROXMOX_HOST}
      - TF_VAR_proxmox_token=${PROXMOX_TOKEN}

Network Architecture and Security

VLAN Segmentation Strategy

Management VLAN (10): Proxmox, switches, APs
Server VLAN (20): Docker hosts, databases  
Monitoring VLAN (30): Grafana, InfluxDB, Wazuh
IoT VLAN (40): Smart home devices
Guest VLAN (50): Isolated guest access

Firewall Rules

# Proxmox firewall configuration
# Allow management access
pvesh set /nodes/proxmox/firewall/rules -type in -action ACCEPT -proto tcp -dport 8006 -source 10.10.10.0/24

# Allow cluster communication  
pvesh set /nodes/proxmox/firewall/rules -type in -action ACCEPT -proto tcp -dport 5404:5405 -source 10.10.20.0/24

# Block inter-VLAN by default
pvesh set /nodes/proxmox/firewall/rules -type in -action DROP -source 10.10.40.0/24 -dest 10.10.20.0/24

Backup and Disaster Recovery

Automated Backup Strategy

# Proxmox backup configuration
pvesm add pbs backup-server --server backup.local --username backup@pam --password secret --fingerprint xx:xx:xx

# Create backup job
vzdump --mode snapshot --compress lzo --storage backup-server --all 1 --mailto [email protected]

Docker Volume Backups

services:
  backup:
    image: offen/docker-volume-backup:latest
    container_name: backup
    restart: always
    environment:
      - BACKUP_FILENAME=backup-%Y-%m-%dT%H-%M-%S.tar.gz
      - BACKUP_CRON_EXPRESSION=0 2 * * *
      - BACKUP_RETENTION_DAYS=14
      - BACKUP_EXCLUDE_REGEXP=.*\.tmp$$
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - backup-data:/backup
      - /opt/backup:/archive

Monitoring and Alerting Configuration

Grafana Dashboard Configuration

Create comprehensive dashboards monitoring:

  • Proxmox cluster health
  • VM/Container resource utilization
  • Docker container status
  • Network throughput and latency
  • Security events from Wazuh
  • TacticalRMM endpoint status

Alert Manager Rules

groups:
  - name: homelab-alerts
    rules:
      - alert: ProxmoxHighCPU
        expr: cpu_usage_active > 85
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High CPU usage on Proxmox host"
          description: "CPU usage is above 85% for more than 5 minutes"

      - alert: DockerContainerDown
        expr: up == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Docker container is down"
          description: "Container {{ $labels.instance }} has been down for more than 1 minute"

Maintenance and Updates

Automated Update Pipeline

# Ansible playbook for system updates
---
- name: Update homelab infrastructure
  hosts: all
  become: yes
  tasks:
    - name: Update Proxmox packages
      apt:
        upgrade: dist
        update_cache: yes
      when: inventory_hostname in groups['proxmox']

    - name: Update Docker containers
      shell: docker-compose pull && docker-compose up -d
      args:
        chdir: /opt/docker-compose
      when: inventory_hostname in groups['docker_hosts']

    - name: Restart services if needed
      systemd:
        name: "{{ item }}"
        state: restarted
      loop:
        - docker
        - networking
      when: reboot_required.changed

Conclusion

This comprehensive Proxmox-based homelab architecture provides enterprise-grade capabilities while remaining cost-effective and educational. The combination of robust virtualization, comprehensive monitoring, automated deployment, and security tooling creates an environment suitable for:

  • Learning and Development: Experiment with new technologies safely
  • Professional Skills Building: Gain hands-on experience with industry-standard tools
  • Testing and Validation: Validate configurations before production deployment
  • Home Automation: Securely host smart home services
  • Personal Cloud: Create your private cloud infrastructure

The modular design allows for incremental implementation - start with the core Proxmox installation and Docker host, then gradually add monitoring, security, and automation components as your skills and requirements grow.

This setup provides the foundation for advanced topics like Kubernetes clusters, CI/CD pipelines, and hybrid cloud integration, making it an investment in both current capabilities and future learning opportunities.

Remember to regularly backup your configurations, keep systems updated, and document your customizations. The homelab journey is as much about the learning process as it is about the destination.