Jordan Ramos
4f69420aaa
Implement comprehensive directory reorganization to improve discoverability,
logical grouping, and separation of concerns across documentation, scripts,
and infrastructure snapshots.
Major Changes:
1. Documentation Reorganization:
- Created start-here-docs/ for onboarding documentation
* Moved QUICK-START.md, START-HERE.md, GIT-SETUP-GUIDE.md
* Moved GIT-QUICK-REFERENCE.md, SCRIPT-USAGE.md, SETUP-COMPLETE.md
- Created troubleshooting/ directory
* Moved BUGFIX-SUMMARY.md for centralized issue resolution
- Created mcp/ directory for Model Context Protocol configurations
* Moved OBSIDIAN-MCP-SETUP.md to mcp/obsidian/
2. Scripts Reorganization:
- Created scripts/crawlers-exporters/ for infrastructure collection
* Moved collect*.sh scripts and collection documentation
* Consolidates Proxmox homelab export tooling
- Created scripts/fixers/ for operational repair scripts
* Moved fix_n8n_db_*.sh scripts
* Isolated scripts with embedded credentials (templates tracked)
- Created scripts/qol/ for quality-of-life utilities
* Moved git-aliases.sh and git-first-commit.sh
3. Infrastructure Snapshots:
- Created disaster-recovery/ for active infrastructure state
* Moved latest homelab-export-20251202-204939/ snapshot
* Contains current VM/CT configurations and system state
- Created archive-homelab/ for historical snapshots
* Moved homelab-export-*.tar.gz archives
* Preserves point-in-time backups for reference
4. Agent Definitions:
- Created sub-agents/ directory
* Added backend-builder.md (development agent)
* Added lab-operator.md (infrastructure operations agent)
* Added librarian.md (git/version control agent)
* Added scribe.md (documentation agent)
5. Updated INDEX.md:
- Reflects new directory structure throughout
- Updated all file path references
- Enhanced navigation with new sections
- Added agent roles documentation
- Updated quick reference commands
6. Security Improvements:
- Updated .gitignore to match reorganized file locations
- Corrected path for scripts/fixers/fix_n8n_db_c_locale.sh exclusion
- Maintained template-based credential management pattern
Infrastructure State Update:
- Latest snapshot: 2025-12-02 20:49:54
- Removed: VM 101 (gitlab), CT 112 (Anytype)
- Added: CT 113 (n8n)
- Total: 9 VMs, 3 Containers
Impact:
- Improved repository navigation and discoverability
- Logical separation of documentation, scripts, and snapshots
- Clearer onboarding path for new users
- Enhanced maintainability through organized structure
- Foundation for multi-agent workflow support
Files changed: 90 files (+935/-349)
- 3 modified, 14 new files, 73 renames/moves
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
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 - gitlab: GitLab CE/EE for source control and CI/CD
- 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
Containers (LXC)
- 102 - nginx: Reverse proxy and load balancer
- 103 - netbox: Network documentation and IPAM
- 112 - Anytype: Knowledge management system
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
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
-
Configure Environment:
cp .env.example .env # Edit .env with your Proxmox host details -
Collect Current Configuration:
./collect-homelab-config.sh -
Review Exported Data:
# 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
.envfile is ignored by git (contains sensitive information) - Exported configurations may contain IP addresses and hostnames
- Review sanitization options in
.envbefore sharing exports - Always use
.env.exampleas 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:
- Fork the repository
- Customize
.envfor your environment - Update VM/CT IDs and names to match your infrastructure
- 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-11-29 Proxmox Version: 8.3.3