Homelab Infrastructure Repository

Version-controlled infrastructure configuration for my Proxmox-based homelab environment.

Overview

This repository contains configuration files, scripts, and documentation for managing a Proxmox VE 8.3.3 homelab environment. The infrastructure follows a hybrid architecture combining traditional virtualization (KVM/QEMU) with containerization (LXC) for optimal resource utilization.

Infrastructure Components

Proxmox Host

• Node: serviceslab
• Version: Proxmox VE 8.3.3
• Architecture: Single-node cluster
• Primary Use: Services and development laboratory

Virtual Machines (QEMU/KVM)

• 100 - docker-hub: Container registry and Docker hub mirror
• 101 - monitoring-docker: Monitoring stack (Grafana/Prometheus/PVE Exporter) at 192.168.2.114
• 105 - dev: General-purpose development environment
• 106 - Ansible-Control: Infrastructure automation control node
• 108 - CML: Cisco Modeling Labs for network simulation
• 109 - web-server-01: Web application server (clustered)
• 110 - web-server-02: Web application server (load-balanced)
• 111 - db-server-01: Database server

VM Templates

• 104 - ubuntu-dev: Ubuntu development environment template for cloning
• 107 - ubuntu-docker: Ubuntu Docker host template for rapid deployment

Containers (LXC)

• 102 - nginx: Reverse proxy and load balancer (Nginx Proxy Manager)
• 103 - netbox: Network documentation and IPAM
• 112 - twingate-connector: Zero-trust network access connector
• 113 - n8n: Workflow automation platform at 192.168.2.107

Storage Pools

• local: System files, ISOs, and templates
• local-lvm: VM disk images (thin provisioned)
• Vault: Secure storage for sensitive data
• PBS-Backups: Proxmox Backup Server repository
• iso-share: Installation media library

Repository Structure

homelab/
├── .env.example          # Template for environment configuration
├── collect*.sh           # Scripts for collecting Proxmox configuration
├── homelab-export-*/     # Exported configuration snapshots
├── CLAUDE.md             # AI assistant guidance for this repository
├── INDEX.md              # Comprehensive documentation index
├── START-HERE.md         # Getting started guide
└── README.md             # This file

Monitoring & Observability

The infrastructure includes a comprehensive monitoring stack deployed on VM 101 (monitoring-docker) at 192.168.2.114:

Components

• Grafana (Port 3000): Visualization and dashboards
• Prometheus (Port 9090): Metrics collection and time-series database
• PVE Exporter (Port 9221): Proxmox VE metrics exporter

Features

• Real-time infrastructure monitoring
• Resource utilization tracking for VMs and containers
• Storage pool metrics and trends
• Network traffic analysis
• Pre-configured Proxmox VE dashboards
• Alerting capabilities

Documentation: See monitoring/README.md for complete setup and configuration guide.

Network Security

Zero-Trust Access

• CT 112 - twingate-connector: Provides secure remote access without traditional VPN
• Technology: Twingate zero-trust network access
• Benefits: Simplified secure access, no complex VPN configurations

Automation & Integration

Workflow Automation

• CT 113 - n8n at 192.168.2.107
• Database: PostgreSQL 15+
• Features: API integrations, scheduled workflows, webhook triggers
• Documentation: See services/README.md for n8n setup and troubleshooting

Quick Start

Prerequisites

• SSH access to your Proxmox server
• Basic familiarity with Linux command line
• WSL2 (if running on Windows) or native Linux environment

Initial Setup

1. Configure Environment:

   cp .env.example .env
   # Edit .env with your Proxmox host details
   

2. Collect Current Configuration:

   ./collect-homelab-config.sh
   

3. Review Exported Data:

   # The script creates timestamped exports in homelab-export-YYYYMMDD-HHMMSS/
   

Scripts

collect-homelab-config.sh

Comprehensive configuration collection script with multiple collection levels:

• basic: Essential configurations only
• standard: Recommended for most users
• full: Detailed system information
• paranoid: Complete infrastructure snapshot

collect-remote.sh

Remote collection wrapper for running collection on Proxmox host via SSH.

collect.sh

Simplified collection interface.

Usage Guides

• START-HERE.md: Complete beginner's guide
• COLLECTION-GUIDE.md: Detailed collection script documentation
• SCRIPT-USAGE.md: Advanced script usage and customization
• INDEX.md: Comprehensive documentation index

Security Notes

• The .env file is ignored by git (contains sensitive information)
• Exported configurations may contain IP addresses and hostnames
• Review sanitization options in .env before sharing exports
• Always use .env.example as template and never commit actual .env

Backup Strategy

• Automated backups via Proxmox Backup Server (PBS-Backups pool)
• Configuration exports stored in timestamped directories
• Version control for Infrastructure as Code changes

Contributing

This is a personal homelab repository. If you're using this as a template:

1. Fork the repository
2. Customize .env for your environment
3. Update VM/CT IDs and names to match your infrastructure
4. Modify scripts as needed for your use case

Documentation

See the following files for detailed information:

• CLAUDE.md: AI assistant context and repository guidelines
• WORKFLOW-DIAGRAM.txt: Visual workflow representation
• QUICK-START.md: Fast-track setup guide

License

This is a personal infrastructure repository. Use at your own risk.

Support

For questions about:

• Proxmox: https://pve.proxmox.com/wiki/Main_Page
• This Repository: See documentation files or create an issue

---

Last Updated: 2025-12-07 Proxmox Version: 8.3.3 Infrastructure: 8 VMs, 2 Templates, 4 LXC Containers