homelab/INDEX.md

Homelab Infrastructure Collection - File Index

Welcome to your homelab infrastructure collection toolkit! This index will help you navigate the various files and understand what each one does.

Quick Navigation

New to this? Start here: QUICK-START.md

Ready to run? Execute: bash collect.sh

Need help? Check: COLLECTION-GUIDE.md

File Inventory

Core Scripts

File	Size	Purpose
collect-homelab-config.sh	32K	Main collection engine - runs on Proxmox host
collect-remote.sh	13K	SSH wrapper - orchestrates remote execution from WSL
collect.sh	4.2K	Convenience wrapper - uses .env configuration

Which script should I use?

• Easiest: collect.sh (if you have .env configured)
• Direct control: collect-remote.sh <proxmox-ip>
• On Proxmox: collect-homelab-config.sh (if SSHed into Proxmox)

Configuration

File	Size	Purpose
.env.example	1.5K	Configuration template with all options
.env	-	YOUR configuration (create from .env.example)

Setup: cp .env.example .env then edit .env with your Proxmox IP

Documentation

File	Size	Purpose	Audience
QUICK-START.md	9.6K	Get started in 5 minutes	First-time users
README-COLLECTION.md	8.5K	Overview and common patterns	General users
COLLECTION-GUIDE.md	15K	Comprehensive reference	Power users
WORKFLOW-DIAGRAM.txt	25K	Visual architecture diagrams	Visual learners
INDEX.md	This file	Navigation and file index	Everyone
CLAUDE.md	5.7K	Project context for Claude	AI assistant

Which Documentation Should I Read?

┌─────────────────────────────────────────────────────┐
│  Just want to get started?                          │
│  → Read: QUICK-START.md                             │
│  → Time: 5 minutes                                  │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│  Want to understand common usage patterns?          │
│  → Read: README-COLLECTION.md                       │
│  → Time: 15 minutes                                 │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│  Need complete reference with all options?          │
│  → Read: COLLECTION-GUIDE.md                        │
│  → Time: 30-45 minutes                              │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│  Visual learner? Want to see the architecture?      │
│  → Read: WORKFLOW-DIAGRAM.txt                       │
│  → Time: 10 minutes                                 │
└─────────────────────────────────────────────────────┘

Typical Workflow

First-Time Setup (5 minutes)

1. Configure environment

   cp .env.example .env
   nano .env  # Set PROXMOX_HOST to your Proxmox IP
   

2. Test SSH access

   ssh root@your-proxmox-ip
   

3. Run first collection

   bash collect.sh
   

4. Review results

   cat exports/homelab-export-*/SUMMARY.md
   

Regular Use (1 minute)

# Just run this whenever you want to snapshot your infrastructure
bash collect.sh

Advanced Use

# Full collection with verbose output
bash collect.sh --level full --verbose

# Sanitized export for sharing
bash collect.sh --sanitize all

# Different Proxmox host
bash collect.sh --host 192.168.1.200

What Gets Created When You Run The Scripts?

After running bash collect.sh, you'll have:

/mnt/c/Users/fam1n/Documents/homelab/
└── exports/
    └── homelab-export-20241128-143022/
        ├── README.md                    # Documentation of this specific export
        ├── SUMMARY.md                   # Statistics and overview
        ├── collection.log               # Detailed collection log
        ├── homelab-export-*.tar.gz      # Compressed archive
        ├── configs/
        │   ├── proxmox/                # Proxmox core configs
        │   ├── vms/                    # All VM configs
        │   ├── lxc/                    # All container configs
        │   ├── storage/                # Storage pool configs
        │   ├── network/                # Network configs
        │   └── backup/                 # Backup job configs
        ├── exports/
        │   ├── system/                 # System information
        │   ├── cluster/                # Cluster status
        │   └── guests/                 # VM/CT details
        ├── docs/                        # For your manual documentation
        ├── scripts/                     # For your automation scripts
        └── diagrams/                    # For network diagrams

Script Capabilities Matrix

Feature	collect.sh	collect-remote.sh	collect-homelab-config.sh
Uses .env config	✓	✗	✗
Runs from WSL	✓	✓	✗
Runs on Proxmox	✗	✗	✓
SSH automation	✓	✓	N/A
File transfer	✓	✓	N/A
Easiest to use	✓	-	-
Most flexible	-	✓	✓

Command Quick Reference

Setup Commands

# First-time configuration
cp .env.example .env
nano .env

# Set up SSH keys (recommended)
ssh-keygen -t ed25519
ssh-copy-id root@<proxmox-ip>

Collection Commands

# Standard collection (default)
bash collect.sh

# Basic collection (minimal)
bash collect.sh --level basic

# Full collection (comprehensive)
bash collect.sh --level full

# With verbose output
bash collect.sh --verbose

# Sanitized (safe for sharing)
bash collect.sh --sanitize all

# Keep copy on Proxmox
bash collect.sh --keep-remote

# Custom output location
bash collect.sh --output ~/backups

Review Commands

# View summary
cat exports/homelab-export-*/SUMMARY.md

# View collection log
less exports/homelab-export-*/collection.log

# List collected files
ls -R exports/homelab-export-*/

# Browse VM configs
cat exports/homelab-export-*/configs/vms/*.conf

# Check storage setup
cat exports/homelab-export-*/configs/proxmox/storage.cfg

Help Commands

# Script help
bash collect.sh --help
bash collect-remote.sh --help
bash collect-homelab-config.sh --help

# Documentation
cat QUICK-START.md
cat README-COLLECTION.md
cat COLLECTION-GUIDE.md
cat WORKFLOW-DIAGRAM.txt

Collection Levels Explained

Level	Time	Size	Contents	Use Case
basic	~30s	1-3 MB	Configs only	Quick snapshots
standard	~1min	2-6 MB	Configs + status	Regular documentation
full	~2min	5-20 MB	Everything	Pre-maintenance backup
paranoid	~5min	10-50 MB	Maximum detail	Disaster recovery planning

Your Infrastructure

Based on the CLAUDE.md context, your environment includes:

Virtual Machines (QEMU/KVM)

• VM 100: docker-hub
• VM 101: gitlab
• VM 105: dev
• VM 106: Ansible-Control
• VM 108: CML (Cisco Modeling Labs)
• VM 109: web-server-01
• VM 110: web-server-02
• VM 111: db-server-01

Containers (LXC)

• CT 102: nginx
• CT 103: netbox
• CT 112: Anytype

Storage Pools

• local (Directory) - 14.8% used
• local-lvm (LVM-Thin) - 0.0% used
• Vault (NFS/Directory) - 11.9% used
• PBS-Backups (Proxmox Backup Server) - 21.6% used
• iso-share (NFS/CIFS) - 1.4% used
• localnetwork (Network share)

All of these will be documented in your collection exports!

Common Questions

Q: Which file do I run?

A: Start with bash collect.sh - it's the easiest.

Q: Do I need to set up .env?

A: Yes! Copy .env.example to .env and set your PROXMOX_HOST.

Q: Will this modify my Proxmox setup?

A: No! All operations are read-only. Zero risk.

Q: How much disk space do I need?

A: On Proxmox: ~100-500 MB. On WSL: ~50-250 MB for archives.

Q: Can I run this regularly?

A: Absolutely! That's what it's designed for. Run weekly or monthly.

Q: What if I get errors?

A: Check SUMMARY.md and collection.log in the export. Most "errors" are just skipped features you don't use (like ZFS if you don't have ZFS).

Q: Is my data secure?

A: By default, passwords and tokens are sanitized. Use --sanitize all for complete sanitization including IPs.

Q: Can I use this for disaster recovery?

A: Yes! The configs show you exactly how your infrastructure is set up. Restore disk images from PBS-Backups and recreate VMs using these configs.

Integration Examples

Git Version Control

cd exports/homelab-export-*/
git init
git add .
git commit -m "Infrastructure snapshot $(date +%Y-%m-%d)"
git remote add origin <your-private-repo>
git push -u origin main

Scheduled Collections (on Proxmox)

# Add to Proxmox crontab
0 3 * * 0 /root/collect-homelab-config.sh -l standard -o /backup/weekly-$(date +\%Y\%U)

Automated Retention

# Keep only last 4 weeks
find ./exports -name "homelab-export-*.tar.gz" -mtime +28 -delete

Troubleshooting Quick Guide

Problem	Solution
"Cannot connect to Proxmox"	Check IP in .env, test with ssh root@<ip>
"Permission denied"	Use bash collect.sh not ./collect.sh on Windows FS
"PROXMOX_HOST not set"	Edit .env file and set your Proxmox IP
"Some items skipped"	Normal! Check SUMMARY.md - usually ZFS/cluster features you don't use
"Script won't execute"	Use: bash collect.sh (explicitly call bash)
SSH asks for password	Set up SSH keys: ssh-copy-id root@<proxmox-ip>

File Sizes Reference

Component	Size	Notes
Scripts	~50K total	All three collection scripts
Documentation	~65K total	All markdown and text files
Configuration	~2K	.env.example template
Total Package	~117K	Everything you need
Output (basic)	1-3 MB	Per collection run
Output (standard)	2-6 MB	Per collection run
Output (full)	5-20 MB	Per collection run

Next Steps

1. Immediate: Read QUICK-START.md (5 minutes)

2. Setup: Create your .env file

   cp .env.example .env
   nano .env  # Set PROXMOX_HOST
   

3. Execute: Run your first collection

   bash collect.sh
   

4. Review: Check the results

   cat exports/homelab-export-*/SUMMARY.md
   

5. Explore: Browse the collected configs

   ls -R exports/homelab-export-*/
   

6. Learn More: Read README-COLLECTION.md for common patterns

7. Master It: Study COLLECTION-GUIDE.md for advanced usage

Support and Resources

• Quick help: bash collect.sh --help
• Detailed help: See COLLECTION-GUIDE.md
• Visual guide: See WORKFLOW-DIAGRAM.txt
• Examples: See README-COLLECTION.md

Summary

You now have a complete, production-ready infrastructure collection system that:

✓ Automatically collects all Proxmox configurations ✓ Works seamlessly from WSL2 via SSH ✓ Sanitizes sensitive information ✓ Creates organized, documented exports ✓ Supports automation and scheduling ✓ Provides comprehensive documentation ✓ Is completely safe (read-only operations)

Ready to begin?

# Set up configuration
cp .env.example .env
nano .env

# Run your first collection
bash collect.sh

---

Package Version: 1.0.0 Created: 2024-11-28 Maintained by: Your homelab automation assistant