homelab/README.md

# 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**:
   ```bash
   cp .env.example .env
   # Edit .env with your Proxmox host details
   ```

2. **Collect Current Configuration**:
   ```bash
   ./collect-homelab-config.sh
   ```

3. **Review Exported Data**:
   ```bash
   # 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*