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** - 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**:
   ```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-12-07*
*Proxmox Version: 8.3.3*
*Infrastructure: 8 VMs, 2 Templates, 4 LXC Containers*