Jordan Ramos
d3dc899b30
Update infrastructure documentation across all files to accurately distinguish between active VMs (8), templates (2), and LXC containers (4). Previously, VM templates 104 (ubuntu-dev) and 107 (ubuntu-docker) were incorrectly counted as active VMs, inflating the total VM count to 10. Changes: - CLAUDE.md: Update Quick Reference and Infrastructure Overview sections - CLAUDE_STATUS.md: Add dedicated VM Templates section with explanatory note - INDEX.md: Separate templates from active VMs in infrastructure inventory - README.md: Add VM Templates section distinguishing from active VMs - Claude_UPDATES.md: Update infrastructure counts in Quick Reference tables - services/README.md: Correct footer infrastructure counts - sub-agents/*.md: Update infrastructure context in all agent prompts This ensures accurate resource tracking and clarifies that templates are immutable base images for cloning, not running workloads. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
182 lines
6.0 KiB
Markdown
182 lines
6.0 KiB
Markdown
# 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*
|