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.4.0 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
- **IP**: 192.168.2.100
- **Version**: Proxmox VE 8.4.0 (kernel 6.8.12-17-pve)
- **Architecture**: Single-node cluster
- **Primary Use**: Services and development laboratory

### Virtual Machines — Running

| VMID | Name | vCPU | RAM | Disk | Purpose |
|------|------|------|-----|------|---------|
| 100 | docker-hub | 4 | 10GB | 100GB | Container registry and Docker hub mirror |
| 101 | monitoring-docker | 2 | 8GB | 50GB | Monitoring stack (Grafana/Prometheus/PVE Exporter) |
| 102 | CML | 8 | 32GB | 200GB | Cisco Modeling Labs — network simulation lab |

### Virtual Machines — Stopped / Templates

| VMID | Name | vCPU | RAM | Notes |
|------|------|------|-----|-------|
| 104 | ubuntu-dev | 2 | 5GB | Template — Ubuntu dev environment |
| 105 | pfSense-Firewall | 2 | 2GB | Stopped — firewall lab VM |
| 106 | Ansible-Control | 2 | 4GB | Stopped — IaC control node |
| 107 | ubuntu-docker | 2 | 4GB | Template — Ubuntu Docker host |
| 114 | haos | 2 | 4GB | Stopped — Home Assistant OS |

### Containers (LXC) — Running

| CTID | Name | vCPU | RAM | IP | Purpose |
|------|------|------|-----|----|---------|
| 109 | caddy | 2 | 2GB | 192.168.2.129 | Reverse proxy and SSL termination (replaced NPM) |
| 112 | twingate-connector | 1 | 1GB | DHCP | Zero-trust network access connector |
| 113 | n8n | 2 | 4GB | 192.168.2.113 | Workflow automation (PostgreSQL 16 + pgvector) |

### Containers (LXC) — Stopped

| CTID | Name | vCPU | RAM | Notes |
|------|------|------|-----|-------|
| 117 | test-cve-database | 4 | 8GB | Stopped — CVE database test environment |

### Storage Pools

| Name | Type | Used | Total | Purpose |
|------|------|------|-------|---------|
| Vault | ZFS Pool | ~2% (110GB) | 4.36TB | Primary VM/CT disk storage |
| PBS-Backups | Proxmox Backup Server | ~29.78% | ~1TB | Automated backup repository |
| iso-share | NFS | ~1.61% | ~3TB | Installation media library |
| local | Directory | ~22.57% | 45GB | System files, ISOs, templates |
| local-lvm | LVM-Thin | ~0.01% | 69GB | VM disk images (thin provisioned) |

### Network

| Bridge | IP | Purpose |
|--------|-----|---------|
| vmbr0 | 192.168.2.100/24 | Primary LAN bridge (eno1) |
| vmbr1 | 192.168.3.0/24 | Internal/isolated bridge |

---

## Repository Structure

```
homelab/
├── services/                    # Docker Compose service configurations
│   ├── n8n/                    # n8n workflow automation
│   └── README.md               # Services overview
├── monitoring/                  # Observability stack configs
│   ├── grafana/
│   ├── prometheus/
│   └── pve-exporter/
├── scripts/
│   ├── crawlers-exporters/     # Infrastructure collection scripts
│   │   ├── collect.sh          # Convenience wrapper (uses .env)
│   │   ├── collect-remote.sh   # SSH wrapper for WSL2
│   │   └── collect-homelab-config.sh  # Main collection engine
│   ├── fixers/                 # Problem-solving scripts
│   └── qol/                    # Git utilities
├── start-here-docs/            # Getting started guides
├── sub-agents/                 # AI agent role definitions
├── troubleshooting/            # Bug fixes and audit findings
├── disaster-recovery/          # Infrastructure export snapshots
├── .env.example                # Configuration template
├── CLAUDE.md                   # AI assistant project context
├── INDEX.md                    # Comprehensive documentation index
└── README.md                   # This file
```

---

## Monitoring & Observability

Deployed on VM 101 (monitoring-docker):

| Component | Port | Purpose |
|-----------|------|---------|
| Grafana | 3000 | Dashboards and visualization |
| Prometheus | 9090 | Metrics collection |
| PVE Exporter | 9221 | Proxmox metrics scraper |

See `monitoring/README.md` for setup and configuration details.

---

## Reverse Proxy

**Caddy** (CT 109, 192.168.2.129) handles reverse proxying and automatic TLS for all services. Replaced Nginx Proxy Manager in early 2026.

---

## Remote Access

**Twingate** (CT 112) provides zero-trust remote access without a traditional VPN. No open inbound firewall rules required.

---

## Workflow Automation

**n8n** (CT 113) runs on PostgreSQL 16 with the pgvector extension for RAG/vector search workflows. See `services/n8n/` for configuration and `scripts/fixers/` for common database repair scripts.

---

## Collecting Your Infrastructure State

```bash
# 1. Configure your environment
cp .env.example .env
nano .env   # Set PROXMOX_HOST=192.168.2.100

# 2. Run the collector
bash scripts/crawlers-exporters/collect.sh

# 3. Review the output
cat homelab-export-*/SUMMARY.md
```

See `start-here-docs/QUICK-START.md` for the full 5-minute setup guide.

---

## Security Notes

- `.env` is git-ignored — never commit it
- Exported configs sanitize passwords and tokens by default
- Review `troubleshooting/` for the December 2025 security audit findings and remediation roadmap
- See `20260331 - Homelab GitOps Optimization Plan` in Obsidian for the full GitOps and security hardening roadmap

---

## Backup Strategy

- **Automated**: Proxmox Backup Server (PBS-Backups pool) handles VM/CT snapshots
- **Config snapshots**: Run `collect.sh` periodically; exports stored in `disaster-recovery/`
- **Repository**: All config changes version-controlled here

---

*Last Updated: 2026-03-31*
*Proxmox Version: 8.4.0*
*Infrastructure: 3 VMs running, 5 VMs stopped/templates, 3 LXC running, 1 LXC stopped*