homelab/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is a homelab infrastructure repository managing a Proxmox VE 8.3.3-based services and development laboratory environment. The infrastructure follows a hybrid architecture pattern combining traditional virtualization (KVM/QEMU) with containerization (LXC) for optimal resource utilization and service isolation.

Infrastructure Overview

Proxmox Environment

• Platform: Proxmox Virtual Environment 8.3.3
• Architecture Pattern: Services/Development Laboratory
• Primary Node: serviceslab (single-node cluster)
• Deployment Model: Hybrid VM + LXC container approach

Key Services & Virtual Machines (QEMU/KVM)

The infrastructure employs full VMs for services requiring kernel-level isolation, complex dependencies, or heavyweight applications:

VM ID	Name	Purpose	Notes
100	docker-hub	Container registry/Docker hub mirror	Local container image caching
101	monitoring-docker	Monitoring stack	Grafana/Prometheus/PVE Exporter at 192.168.2.114
104	ubuntu-dev	Ubuntu development environment	Additional dev workstation
105	dev	Development environment	General-purpose development workstation
106	Ansible-Control	Automation control node	IaC orchestration, configuration management
107	ubuntu-docker	Ubuntu Docker host	Docker-focused environment
108	CML	Cisco Modeling Labs	Network simulation/testing environment
109	web-server-01	Web application server	Production-like web tier (clustered)
110	web-server-02	Web application server	Load-balanced pair with web-server-01
111	db-server-01	Database server	Backend data tier

Containers (LXC)

Lightweight services leveraging LXC for reduced overhead and faster provisioning:

CT ID	Name	Purpose	Notes
102	nginx	Reverse proxy/load balancer	Front-end traffic management (NPM)
103	netbox	Network documentation/IPAM	Infrastructure source of truth
112	twingate-connector	Zero-trust network access	Secure remote access connector
113	n8n	Workflow automation	n8n.io platform at 192.168.2.107

Storage Architecture

The storage layout demonstrates a well-organized approach to data separation:

Storage Pool	Type	Usage	Purpose
local	Directory	15.13%	System files, ISOs, templates
local-lvm	LVM-Thin	0.0%	VM disk images (thin provisioned)
Vault	NFS/Directory	10.88%	Secure storage for sensitive data
PBS-Backups	Proxmox Backup Server	27.43%	Automated backup repository
iso-share	NFS/CIFS	1.4%	Installation media library
localnetwork	Network share	N/A	Shared resources across infrastructure

Architecture Patterns & Design Decisions

Tiered Application Architecture: The infrastructure implements a classic three-tier design with dedicated web servers (109, 110), database server (111), and reverse proxy (102), suggesting this lab is used for practicing production-like deployments.

Automation-First Approach: The presence of Ansible-Control (106), GitLab (101), and NetBox (103) indicates a focus on Infrastructure as Code and proper documentation practices—rather civilized.

Network Simulation Capability: CML (108) suggests network engineering activities, possibly testing configurations before production deployment.

Container Strategy: The selective use of LXC for stateless or lightweight services (nginx, netbox, twingate, n8n) vs full VMs for complex applications demonstrates thoughtful resource optimization.

Monitoring & Observability: The dedicated monitoring VM (101) with Grafana, Prometheus, and PVE Exporter provides comprehensive infrastructure visibility, enabling proactive capacity planning and performance optimization.

Zero-Trust Security: Implementation of Twingate connector (CT 112) demonstrates modern security practices, providing secure remote access without traditional VPN complexity.

Working with This Environment

Universal Workflow

For every complex task, every Agent must follow this loop:

1. Read: cat CLAUDE_STATUS.md to see where we are.
2. Execute: Perform your specific task (Coding, Docs, Sysadmin).
3. Update: Edit CLAUDE_STATUS.md to mark your step as [x] and update the "Current Context".

Status File Template

If CLAUDE_STATUS.md is missing, initialize it with:

• Goal: [User Goal]
• Phase: [Planning / Dev / Deploy]
• Checklist: [List of steps]

Best Practices

1. Backup Strategy: With PBS-Backups at 21.6% utilization and excellent uptime (27-68 days), ensure regular backup schedules are maintained. Consider implementing the 3-2-1 rule if not already in place.

2. Resource Management: Monitor the local-lvm pool (currently 0.0%)—this appears to be reserved capacity. Ensure thin provisioning doesn't lead to overcommitment.

3. Configuration Management: Utilize the Ansible-Control node (106) for infrastructure changes. Avoid manual configuration drift.

4. Documentation: NetBox (103) should be the single source of truth for IP addressing, VLANs, and service inventory. Keep it updated.

5. Version Control: GitLab (101) should house all Infrastructure as Code, scripts, and configuration files from this repository.

6. Load Balancing: The paired web servers (109, 110) suggest HA testing—ensure nginx (102) is properly configured for failover.

Access Patterns

• Proxmox Web UI: Primary management interface for VM/CT lifecycle operations
• Ansible: Automated configuration deployment and orchestration
• GitLab: CI/CD pipelines for infrastructure testing and deployment
• NetBox: Network documentation and IP address management

Maintenance Considerations

• Uptime: Services showing 27-68 days uptime—schedule maintenance windows for kernel updates
• Storage Growth: PBS-Backups at 21.6% allows healthy retention; review backup policies quarterly
• Capacity Planning: Current utilization suggests comfortable headroom; monitor trends via Proxmox metrics

Development Setup

The repository structure will house:

• Ansible playbooks and roles for infrastructure automation
• Terraform/OpenTofu configurations for Proxmox resource provisioning
• Docker Compose files for service definitions
• Documentation and runbooks for common operations
• Network diagrams and architecture documentation

Notes

• This is a Windows Subsystem for Linux (WSL2) environment
• Working directory: /mnt/c/Users/fam1n/Documents/homelab
• This repository is not yet initialized as a git repository
• Proxmox node serviceslab is the single point of management
• Infrastructure demonstrates production-like patterns suitable for learning and testing