Jordan Ramos
a1841f1c41
- Add Obsidian MCP server setup guide for WSL2 integration (820 lines) - Add comprehensive n8n workflow automation deployment plan (1,948 lines) - Add agent workflow coordination via CLAUDE_STATUS.md - Update CLAUDE.md with universal agent workflow protocol - Remove deprecated homelab-steve agent definition - Enhance .gitignore with Claude config exclusions Security: API key sanitized, no production secrets exposed Infrastructure Impact: None (documentation only) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
123 lines
6.1 KiB
Markdown
123 lines
6.1 KiB
Markdown
# 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 | gitlab | GitLab CE/EE instance | Source control, CI/CD platform |
|
|
| 105 | dev | Development environment | General-purpose development workstation |
|
|
| 106 | Ansible-Control | Automation control node | IaC orchestration, configuration management |
|
|
| 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 |
|
|
| 103 | netbox | Network documentation/IPAM | Infrastructure source of truth |
|
|
| 112 | Anytype | Knowledge management | Personal/team documentation |
|
|
|
|
### Storage Architecture
|
|
|
|
The storage layout demonstrates a well-organized approach to data separation:
|
|
|
|
| Storage Pool | Type | Usage | Purpose |
|
|
|--------------|------|-------|---------|
|
|
| local | Directory | 14.8% | System files, ISOs, templates |
|
|
| local-lvm | LVM-Thin | 0.0% | VM disk images (thin provisioned) |
|
|
| Vault | NFS/Directory | 11.9% | Secure storage for sensitive data |
|
|
| PBS-Backups | Proxmox Backup Server | 21.6% | 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) vs full VMs for complex applications demonstrates thoughtful resource optimization.
|
|
|
|
## 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
|