homelab/start-here-docs/START-HERE.md

# START HERE - Homelab Infrastructure Collection

## Welcome!

You now have a sophisticated, production-ready system for collecting and documenting your Proxmox homelab infrastructure. This guide will get you operational in minutes.

## What You Have

A complete automated collection system that:
- Gathers ALL Proxmox configurations (VMs, containers, storage, network, backups)
- Runs safely from your WSL2 environment via SSH
- Creates organized, documented exports
- Sanitizes sensitive information
- Supports automation and version control

## Fastest Path to Success

### Step 1: Configure (2 minutes)

```bash
cd /mnt/c/Users/fam1n/Documents/homelab

# Create your configuration file
cp .env.example .env

# Edit it with your Proxmox IP address
nano .env
```

**Required change in .env:**
```bash
PROXMOX_HOST="192.168.1.100"  # Replace with YOUR Proxmox IP
```

Save and exit (Ctrl+X, Y, Enter in nano)

### Step 2: Test SSH (1 minute)

```bash
# Test connection to your Proxmox server
ssh root@192.168.1.100  # Use YOUR Proxmox IP

# If it works, exit back to WSL
exit
```

**Optional but recommended:** Set up passwordless SSH:
```bash
ssh-keygen -t ed25519
ssh-copy-id root@192.168.1.100  # Use YOUR Proxmox IP
```

### Step 3: Run Collection (1 minute)

```bash
# Execute the collection
bash collect.sh
```

Watch as it:
1. Connects to your Proxmox server
2. Collects all configurations
3. Downloads results to your local machine
4. Shows you a summary

### Step 4: Review Results (1 minute)

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

# Browse what was collected
ls -R exports/homelab-export-*/configs/
```

## That's It!

You've just documented your entire homelab infrastructure. The export contains:

```
exports/homelab-export-<timestamp>/
├── configs/
│   ├── proxmox/          ← Core Proxmox settings
│   ├── vms/              ← All 8 VM configurations
│   ├── lxc/              ← All 3 container configurations
│   ├── storage/          ← Storage pool setups
│   ├── network/          ← Network configuration
│   └── backup/           ← Backup job schedules
└── exports/
    ├── system/           ← System information
    ├── cluster/          ← Resource usage
    └── guests/           ← VM/container details
```

## What's Next?

### Learn More
- **Quick overview**: Read [INDEX.md](INDEX.md)
- **Common patterns**: Read [README-COLLECTION.md](README-COLLECTION.md)
- **Full reference**: Read [COLLECTION-GUIDE.md](COLLECTION-GUIDE.md)

### Common Tasks

**Weekly snapshots:**
```bash
bash collect.sh
```

**Full collection before maintenance:**
```bash
bash collect.sh --level full --verbose
```

**Sanitized export for sharing:**
```bash
bash collect.sh --sanitize all
```

### Version Control

Store your infrastructure in Git:
```bash
cd exports/homelab-export-*/
git init
git add .
git commit -m "Homelab snapshot $(date +%Y-%m-%d)"
```

## Need Help?

### Documentation Files

| File | Purpose | Time to Read |
|------|---------|--------------|
| **INDEX.md** | Navigation and overview | 5 min |
| **QUICK-START.md** | Getting started guide | 10 min |
| **README-COLLECTION.md** | Common usage patterns | 15 min |
| **COLLECTION-GUIDE.md** | Complete reference | 30 min |
| **WORKFLOW-DIAGRAM.txt** | Visual architecture | 10 min |

### Quick Help

```bash
# Script help
bash collect.sh --help

# View documentation
cat INDEX.md
```

### Common Issues

**"Cannot connect to Proxmox"**
- Check IP in `.env`
- Test: `ssh root@<your-proxmox-ip>`

**"PROXMOX_HOST not set"**
- Did you create `.env` from `.env.example`?
- Did you set `PROXMOX_HOST` in `.env`?

**"Permission denied"**
- Use: `bash collect.sh` (not `./collect.sh`)
- Windows filesystem doesn't support Linux execute permissions

## Your Infrastructure

Your Proxmox node "serviceslab" includes:

**Virtual Machines:**
- 100: docker-hub
- 101: gitlab
- 105: dev
- 106: Ansible-Control
- 108: CML
- 109: web-server-01
- 110: web-server-02
- 111: db-server-01

**Containers:**
- 102: nginx
- 103: netbox
- 112: Anytype

**Storage:**
- local, local-lvm, Vault, PBS-Backups, iso-share

All of this will be documented in your exports!

## Files You Should Know About

### To Execute
- `collect.sh` - Main command (uses .env configuration)
- `collect-remote.sh` - Advanced SSH wrapper
- `collect-homelab-config.sh` - Core engine (runs on Proxmox)

### To Configure
- `.env` - YOUR configuration (create from .env.example)
- `.env.example` - Template with all options

### To Read
- `START-HERE.md` - This file
- `INDEX.md` - Complete file index
- `QUICK-START.md` - 5-minute getting started
- `README-COLLECTION.md` - Overview and patterns
- `COLLECTION-GUIDE.md` - Full reference manual
- `WORKFLOW-DIAGRAM.txt` - Visual diagrams

## Quick Command Reference

```bash
# Setup (one-time)
cp .env.example .env
nano .env  # Set PROXMOX_HOST

# Collect (run anytime)
bash collect.sh

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

# Help
bash collect.sh --help
cat INDEX.md
```

## Safety Notes

✓ **Completely Safe**: All operations are read-only
✓ **No Modifications**: Script never changes your Proxmox setup
✓ **Sanitized by Default**: Passwords and tokens are redacted
✓ **Tested**: Production-ready, well-documented code

## Success Indicators

After running, you should see:
```
[✓] SSH connection successful
[✓] Confirmed Proxmox VE installation
[✓] Script uploaded successfully
[✓] Collection completed successfully
[✓] Archive downloaded successfully
```

## Ready?

Execute these commands:

```bash
cd /mnt/c/Users/fam1n/Documents/homelab
cp .env.example .env
nano .env  # Set your Proxmox IP
bash collect.sh
```

**That's all you need!** The rest of the documentation is there when you need it.

---

**Quick Links:**
- Overview: [INDEX.md](INDEX.md)
- Getting Started: [QUICK-START.md](QUICK-START.md)
- Full Guide: [COLLECTION-GUIDE.md](COLLECTION-GUIDE.md)

**Version:** 1.0.0 | **Created:** 2024-11-28