ajarbot/memory_workspace/homelab-repo-updates/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

# 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