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 - gitlab: GitLab CE/EE for source control and CI/CD
• 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

Containers (LXC)

• 102 - nginx: Reverse proxy and load balancer
• 103 - netbox: Network documentation and IPAM
• 112 - Anytype: Knowledge management system

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

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-11-29 Proxmox Version: 8.3.3