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](QUICK-START.md)**

**Ready to run?** Execute: `bash collect.sh`

**Need help?** Check: **[COLLECTION-GUIDE.md](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**
   ```bash
   cp .env.example .env
   nano .env  # Set PROXMOX_HOST to your Proxmox IP
   ```

2. **Test SSH access**
   ```bash
   ssh root@your-proxmox-ip
   ```

3. **Run first collection**
   ```bash
   bash collect.sh
   ```

4. **Review results**
   ```bash
   cat exports/homelab-export-*/SUMMARY.md
   ```

### Regular Use (1 minute)

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

### Advanced Use

```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
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)
```bash
# Add to Proxmox crontab
0 3 * * 0 /root/collect-homelab-config.sh -l standard -o /backup/weekly-$(date +\%Y\%U)
```

### Automated Retention
```bash
# 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](QUICK-START.md) (5 minutes)

2. **Setup**: Create your `.env` file
   ```bash
   cp .env.example .env
   nano .env  # Set PROXMOX_HOST
   ```

3. **Execute**: Run your first collection
   ```bash
   bash collect.sh
   ```

4. **Review**: Check the results
   ```bash
   cat exports/homelab-export-*/SUMMARY.md
   ```

5. **Explore**: Browse the collected configs
   ```bash
   ls -R exports/homelab-export-*/
   ```

6. **Learn More**: Read [README-COLLECTION.md](README-COLLECTION.md) for common patterns

7. **Master It**: Study [COLLECTION-GUIDE.md](COLLECTION-GUIDE.md) for advanced usage

## Support and Resources

- **Quick help**: `bash collect.sh --help`
- **Detailed help**: See [COLLECTION-GUIDE.md](COLLECTION-GUIDE.md)
- **Visual guide**: See [WORKFLOW-DIAGRAM.txt](WORKFLOW-DIAGRAM.txt)
- **Examples**: See [README-COLLECTION.md](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?**

```bash
# 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