jramos/homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(repo): reorganize repository structure for improved navigation and maintainability

Browse Source 
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>
This commit is contained in:
Jordan Ramos
2025-12-02 21:39:33 -07:00
parent eec4c4b298
commit 4f69420aaa
90 changed files with 935 additions and 349 deletions
Download Patch File Download Diff File Expand all files Collapse all files

189
start-here-docs/GIT-QUICK-REFERENCE.md Normal file
View File

@@ -0,0 +1,189 @@
# Git Quick Reference Card
## Essential Locations
| What | Path |
|------|------|
| **WSL2 Terminal** | `cd /home/jramos/homelab` |
| **Windows Explorer** | `\\wsl$\Ubuntu\home\jramos\homelab` |
| **Git Repository** | `/home/jramos/homelab/.git/` |
## Daily Commands
### Check What's Changed
```bash
cd /home/jramos/homelab
git status # Show changed files
git diff # Show exact changes
```
### Commit Your Changes
```bash
git add . # Stage all changes
git commit -m "Description here" # Commit with message
```
### View History
```bash
git log # Detailed history
git log --oneline # Compact history
git log -5 # Last 5 commits
```
## Emergency Commands
### Undo Changes (Not Yet Committed)
```bash
git checkout -- filename.sh # Undo changes to one file
git checkout -- . # Undo all changes (CAREFUL!)
```
### Undo Last Commit (Keep Changes)
```bash
git reset --soft HEAD~1 # Undo commit, keep changes staged
git reset HEAD~1 # Undo commit, keep changes unstaged
```
### See What a Commit Changed
```bash
git show <commit-hash> # Show changes in specific commit
git show HEAD # Show changes in last commit
```
## First-Time Setup
### Configure Git Identity
```bash
git config --global user.name "Your Name"
git config --global user.email "your@email.com"
```
### Make First Commit
```bash
cd /home/jramos/homelab
./git-first-commit.sh # Use helper script
```
## File Status Guide
| Status | Meaning | What To Do |
|--------|---------|------------|
| **Untracked** | New file, not in git | `git add filename` |
| **Modified** | Changed since last commit | `git add filename` |
| **Staged** | Ready to commit | `git commit -m "message"` |
| **Committed** | Saved in history | Nothing (it's saved!) |
## Common Workflows
### After Editing Files
```bash
1. git status # See what changed
2. git diff # Review changes
3. git add . # Stage everything
4. git commit -m "msg" # Save changes
5. git log --oneline -3 # Verify commit
```
### Before Major Changes
```bash
1. git status # Check for uncommitted changes
2. git add . # Stage current work
3. git commit -m "Checkpoint before changes"
4. # Now make risky changes
5. # If it breaks: git checkout -- .
```
### Review File History
```bash
git log --oneline filename.sh # See commits for file
git log --follow filename.sh # Include renames
git show <hash>:filename.sh # Show old version
```
## Common Mistakes & Fixes
### "I Committed the Wrong Thing"
```bash
git reset --soft HEAD~1 # Undo commit, keep changes
# Fix what you need to fix
git add .
git commit -m "Correct message"
```
### "I Deleted a File by Accident"
```bash
git checkout -- filename.sh # Restore from last commit
```
### "I Want to See Old Version of File"
```bash
git log --oneline filename.sh # Find commit hash
git show <hash>:filename.sh # View old version
git checkout <hash> -- filename.sh # Restore old version
```
### "Git is Asking for Username/Password"
You're trying to push/pull from a remote that doesn't exist yet.
If you just want local version control, ignore this.
## What NOT to Commit
Already configured in `.gitignore`:
- `.env` (contains secrets)
- `*.iso`, `*.qcow2` (too large)
- `*.tar.gz` (compressed archives)
- `*.log` (log files)
- `secrets/` (sensitive data)
- `homelab-export-*/` (exports)
## Helpful Aliases (Optional)
Add to `~/.bashrc` or `~/.zshrc`:
```bash
alias gs='git status'
alias ga='git add'
alias gc='git commit -m'
alias gl='git log --oneline'
alias gd='git diff'
alias ghome='cd /home/jramos/homelab'
```
Then reload: `source ~/.bashrc`
## Quick Troubleshooting
| Problem | Solution |
|---------|----------|
| "not a git repository" | `cd /home/jramos/homelab` |
| "chmod failed" | You're in `/mnt/c/...` instead of `/home/...` |
| "nothing to commit" | No changes made since last commit |
| "Please tell me who you are" | Set `user.name` and `user.email` |
## Help Commands
```bash
git help # General help
git help commit # Help for specific command
git status # Usually suggests what to do next
```
## Remember
1. **Commit early, commit often**
2. **Write meaningful commit messages**
3. **Review with `git status` and `git diff` before committing**
4. **Never commit `.env` or secrets**
5. **Git is forgiving—you can almost always undo mistakes**
## Quick Workflow Reminder
```
Edit files → git status → git diff → git add . → git commit -m "message"
```
That's 95% of what you'll use daily.
---
**For detailed explanations**: See `GIT-SETUP-GUIDE.md`
**For your first commit**: Run `./git-first-commit.sh`

370
start-here-docs/GIT-SETUP-GUIDE.md Normal file
View File

@@ -0,0 +1,370 @@
# Git Setup Guide for WSL2 Homelab
## The Problem We Solved
When working with git in WSL2 (Windows Subsystem for Linux), you encountered a common issue: **git cannot properly manage repositories on Windows filesystems** (like `/mnt/c/Users/...`).
### Why This Happens
Git requires specific POSIX file permissions and attributes that Windows' NTFS filesystem doesn't support. When git tries to create lock files (like `.git/config.lock`), it fails because:
1. Windows filesystems don't support the same permission model as Linux
2. WSL2 translates permissions, but this breaks git's lock file mechanism
3. Git needs to atomically create/rename files with specific permissions
The error you saw was:
```
error: chmod on .git/config.lock failed: Operation not permitted
```
This is git saying "I can't set the proper permissions on my lock file."
## The Solution We Implemented
We moved your repository to the **Linux filesystem** where git works properly, while keeping it accessible from Windows.
### What We Did
1. **Created a new directory in Linux filesystem**: `/home/jramos/homelab`
- This is a "real" Linux filesystem with proper permission support
- Git works perfectly here
2. **Copied all your files** from the Windows location to the Linux location
3. **Initialized git properly** in the Linux filesystem
4. **Made it accessible from Windows** via the special `\\wsl$\` network path
## Your Repository Locations
### Linux Path (Use this in WSL2 terminal)
```bash
cd /home/jramos/homelab
```
### Windows Path (Use this in File Explorer)
```
\\wsl$\Ubuntu\home\jramos\homelab
```
To access from Windows:
1. Open File Explorer
2. In the address bar, type: `\\wsl$\Ubuntu\home\jramos\homelab`
3. Press Enter
4. You can bookmark this location for easy access
**Pro Tip**: You can map this as a network drive:
- Right-click on "This PC" in File Explorer
- Choose "Map network drive"
- Use the path: `\\wsl$\Ubuntu\home\jramos\homelab`
## What About Your Old Windows Directory?
You have two options:
### Option 1: Keep Windows Directory as Working Copy (Recommended)
Keep using `/mnt/c/Users/fam1n/Documents/homelab` for day-to-day work, and manually sync changes to the git repository when needed:
```bash
# After making changes in Windows location, sync to git repo:
rsync -av --exclude='.git' /mnt/c/Users/fam1n/Documents/homelab/ /home/jramos/homelab/
# Then commit in the git repo:
cd /home/jramos/homelab
git add .
git commit -m "Updated configurations"
```
### Option 2: Fully Switch to Linux Location
Start working exclusively in `/home/jramos/homelab`. You can delete or archive the Windows directory.
## Your First Git Commit
### Quick Method
Run the helper script:
```bash
cd /home/jramos/homelab
./git-first-commit.sh
```
This interactive script will:
1. Set up your git username and email (if not already configured)
2. Show you what will be committed
3. Create your initial commit
4. Explain what to do next
### Manual Method
If you prefer to do it manually:
```bash
cd /home/jramos/homelab
# Configure your identity (one-time setup)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
# Check what files will be committed
git status
# Add all files to staging area
git add .
# Create your first commit
git commit -m "Initial commit: Homelab infrastructure repository"
# View your commit
git log
```
## Files That Are Ignored by Git
The `.gitignore` file tells git to **not** track certain files. Here's what's ignored:
### Sensitive Information
- `.env` - Your actual environment configuration (contains passwords, IPs, etc.)
- `*.key`, `*.pem` - Private keys and certificates
- `secrets/` - Any directory for secrets
- `credentials.json` - Credential files
### Large Files
- `*.iso` - ISO images (too large for git)
- `*.qcow2`, `*.vmdk` - Virtual machine disk images
- `*.tar.gz`, `*.zip` - Compressed archives
### Temporary Files
- `*.log` - Log files
- `*.tmp` - Temporary files
- `backups/` - Backup directories
- `homelab-export-*/` - Your export directories (unless you want them tracked)
### What IS Tracked
- All your scripts (`.sh` files)
- Documentation (`.md` files)
- `.env.example` - Template for environment configuration
- Configuration files
## Common Git Commands for Beginners
### Checking Status
```bash
cd /home/jramos/homelab
git status # See what's changed
```
### Making Changes and Committing
```bash
# Edit your files, then...
git status # See what you changed
git diff # See exactly what changed (detailed)
git add filename.sh # Stage a specific file
git add . # Stage all changes
git commit -m "Description" # Commit with a message
```
### Viewing History
```bash
git log # See all commits (detailed)
git log --oneline # See commits (compact)
git log --graph --oneline # See commits with graph
```
### Undoing Changes
```bash
# Undo changes in a file (before staging)
git checkout -- filename.sh
# Unstage a file (undo git add)
git reset filename.sh
# See changes in a specific commit
git show <commit-hash>
# Revert to a previous version
git checkout <commit-hash> -- filename.sh
```
### Comparing Versions
```bash
# See what changed since last commit
git diff
# See what's staged for commit
git diff --staged
# Compare with a specific commit
git diff <commit-hash>
```
## Best Practices for Your Homelab
### 1. Commit Often, Commit Early
Don't wait until you have "perfect" changes. Commit each logical change:
```bash
# Good commit messages:
git commit -m "Add Ansible playbook for nginx configuration"
git commit -m "Update Proxmox backup schedule to daily"
git commit -m "Fix network interface configuration for web-server-01"
```
### 2. Write Descriptive Commit Messages
```bash
# Bad:
git commit -m "updates"
git commit -m "fix"
# Good:
git commit -m "Update GitLab VM memory from 4GB to 8GB for better performance"
git commit -m "Fix nginx reverse proxy configuration for NetBox"
```
### 3. Before Making Major Changes
Create a commit first, so you can easily undo:
```bash
git add .
git commit -m "Checkpoint before restructuring network configuration"
# Now make your risky changes
# If things break: git checkout -- filename
```
### 4. Review Before Committing
```bash
git status # What files changed?
git diff # What exactly changed?
git add . # Stage everything
git status # Double-check what's staged
git commit -m "Your message"
```
### 5. Keep .env Secure
**NEVER** commit your `.env` file. It's already in `.gitignore`, but be careful:
```bash
# This is safe (only adds .env.example):
git add .
# This would be dangerous (explicitly adds .env, bypassing .gitignore):
git add -f .env # DON'T DO THIS!
```
## Workflow Example
Here's a typical workflow when you make changes:
```bash
# 1. Navigate to your repository
cd /home/jramos/homelab
# 2. Make changes to your files
nano collect-homelab-config.sh # Edit your script
# 3. Test your changes
./collect-homelab-config.sh
# 4. Review what changed
git status
git diff collect-homelab-config.sh
# 5. Stage the changes
git add collect-homelab-config.sh
# 6. Commit with a descriptive message
git commit -m "Add paranoid collection level to homelab collection script
- Added new PARANOID level with complete system snapshot
- Includes kernel modules, network statistics, and process list
- Updated documentation in COLLECTION-GUIDE.md"
# 7. View your history
git log --oneline -5 # Show last 5 commits
```
## Troubleshooting
### "I'm in the wrong directory"
```bash
pwd # Where am I?
cd /home/jramos/homelab # Go to the right place
```
### "Git says 'not a git repository'"
```bash
# Check if .git directory exists
ls -la /home/jramos/homelab/.git
# If it doesn't exist, you're in the wrong place
cd /home/jramos/homelab
```
### "I committed something I shouldn't have"
```bash
# Undo the last commit but keep the changes
git reset --soft HEAD~1
# Undo the last commit AND discard the changes
git reset --hard HEAD~1 # CAREFUL: This deletes your work!
```
### "I want to see what changed in a commit"
```bash
git log --oneline # Find the commit hash
git show <commit-hash> # See the changes
```
### "I accidentally changed a file"
```bash
# Undo changes (before git add)
git checkout -- filename.sh
# Undo staged changes (after git add)
git reset filename.sh
git checkout -- filename.sh
```
## Next Steps
1. **Make your first commit**:
```bash
cd /home/jramos/homelab
./git-first-commit.sh
```
2. **Start tracking changes**: Every time you modify scripts or configurations, commit them
3. **Learn as you go**: Git has many features, but you only need the basics to start
4. **Consider remote backup**: Later, you might want to push your repository to GitHub/GitLab for backup
## Why Version Control Matters for Homelabs
Version control gives you:
1. **History**: See what changed and when
2. **Undo**: Revert mistakes easily
3. **Documentation**: Commit messages explain why changes were made
4. **Backup**: Your configuration history is preserved
5. **Experimentation**: Try things without fear—you can always go back
Think of it as "time travel for your infrastructure configurations."
## Additional Resources
### Learning Git
- **Git Documentation**: https://git-scm.com/doc
- **GitHub Git Handbook**: https://guides.github.com/introduction/git-handbook/
- **Interactive Git Tutorial**: https://learngitbranching.js.org/
### Git Cheat Sheets
- https://training.github.com/downloads/github-git-cheat-sheet/
### Advanced Topics (For Later)
- Branching and merging
- Remote repositories (GitHub, GitLab)
- Git hooks for automation
- Using git with Infrastructure as Code
---
**Remember**: Git is a tool to make your life easier. Start simple, commit often, and learn as you go. You don't need to master everything at once.
If you run into issues, the git community is huge and helpful. Most problems you encounter have been solved before—just search for the error message.
Happy version controlling!

429
start-here-docs/QUICK-START.md Normal file
View File

@@ -0,0 +1,429 @@
# Homelab Collection - Quick Start Guide
Welcome! This guide will get you up and running with automated homelab infrastructure collection in under 5 minutes.
## What This Does
Automatically collects your entire Proxmox homelab configuration including:
- ✓ All VM configurations
- ✓ All LXC container configurations
- ✓ Storage pool definitions
- ✓ Network configurations
- ✓ Backup job schedules
- ✓ System information
- ✓ Cluster resources
**Completely safe** - read-only operations, no modifications to your system.
## Prerequisites Checklist
- [ ] Proxmox VE server running (yours: `serviceslab`)
- [ ] SSH access to Proxmox from WSL
- [ ] Proxmox IP address or hostname
## 5-Minute Setup
### Step 1: Test SSH Access
```bash
# Replace with your Proxmox IP
ssh root@192.168.1.100
```
If you get a password prompt, set up SSH keys (recommended):
```bash
ssh-keygen -t ed25519 -f ~/.ssh/homelab
ssh-copy-id -i ~/.ssh/homelab root@192.168.1.100
```
### Step 2: Configure Your Environment
```bash
cd /mnt/c/Users/fam1n/Documents/homelab
# Copy the example configuration
cp .env.example .env
# Edit with your Proxmox details
nano .env # or use 'code .env' for VS Code
```
Minimum required change in `.env`:
```bash
PROXMOX_HOST="192.168.1.100" # Change to your Proxmox IP
```
### Step 3: Run Your First Collection
```bash
# Simple! Just run:
bash collect.sh
```
That's it! The script will:
1. SSH to your Proxmox server
2. Collect all configurations
3. Download results to `./exports/`
4. Show you a summary
### Step 4: Review Your Export
```bash
# View the summary
cat exports/homelab-export-*/SUMMARY.md
# Browse collected configs
ls -la exports/homelab-export-*/configs/
```
## What Just Happened?
Your infrastructure is now documented! Here's what you have:
```
exports/homelab-export-20241128-143000/
├── configs/
│ ├── proxmox/ ← Core Proxmox settings
│ ├── vms/ ← All your VMs (100-docker-hub, 101-gitlab, etc.)
│ ├── lxc/ ← All containers (102-nginx, 103-netbox, etc.)
│ ├── storage/ ← Storage pools (Vault, PBS-Backups, etc.)
│ ├── network/ ← Network configuration
│ └── backup/ ← Backup jobs
├── exports/
│ ├── system/ ← System info (CPU, RAM, disk, etc.)
│ └── cluster/ ← Resource usage
├── README.md ← Complete documentation
└── SUMMARY.md ← What was collected
```
## Next Steps
### Immediate Actions
1. **Review your infrastructure**
```bash
# See your VM configs
cat exports/homelab-export-*/configs/vms/*.conf
# Check storage setup
cat exports/homelab-export-*/configs/proxmox/storage.cfg
```
2. **Store safely**
```bash
# Initialize git repository
cd exports/homelab-export-*/
git init
git add .
git commit -m "Initial homelab snapshot"
```
3. **Schedule automatic collections** (see Automation section below)
### Common Commands
```bash
# Standard collection (default)
bash collect.sh
# Full collection with everything
bash collect.sh --level full --verbose
# Quick basic snapshot
bash collect.sh --level basic
# Sanitized export (safe for sharing)
bash collect.sh --sanitize all
# Override Proxmox host
bash collect.sh --host 192.168.1.200
```
## Automation
### Weekly Snapshots
On your Proxmox server, run:
```bash
# SSH to Proxmox
ssh root@your-proxmox-ip
# Copy the collection script
cat > /root/collect-homelab-config.sh
# Paste the script content, then Ctrl+D
# Make executable
chmod +x /root/collect-homelab-config.sh
# Add to crontab for weekly Sunday 3 AM runs
crontab -e
```
Add this line:
```cron
0 3 * * 0 /root/collect-homelab-config.sh -l standard -o /backup/homelab/weekly-$(date +\%Y\%U) 2>&1 | logger -t homelab-collection
```
## Understanding Your Infrastructure
Now that you have the export, here's what you can learn:
### Your Virtual Machines
Based on your environment, you should see configs for:
- `100-docker-hub.conf` - Your container registry
- `101-gitlab.conf` - GitLab CE/EE instance
- `105-dev.conf` - Development environment
- `106-Ansible-Control.conf` - Automation control node
- `108-CML.conf` - Cisco Modeling Labs
- `109-web-server-01.conf` - Web server (clustered)
- `110-web-server-02.conf` - Web server (clustered)
- `111-db-server-01.conf` - Database server
### Your Containers
- `102-nginx.conf` - Reverse proxy/load balancer
- `103-netbox.conf` - Network documentation/IPAM
- `112-Anytype.conf` - Knowledge management
### Your Storage
Check `configs/proxmox/storage.cfg` to see:
- local (Directory) - System storage
- local-lvm (LVM-Thin) - VM disk images
- Vault (NFS/Directory) - Secure storage
- PBS-Backups (Proxmox Backup Server) - Backup repository
- iso-share (NFS/CIFS) - Installation media
## Files in This Directory
| File | Purpose |
|------|---------|
| `collect.sh` | **Start here** - Easy wrapper that uses .env |
| `collect-remote.sh` | Advanced - Direct remote execution |
| `collect-homelab-config.sh` | Core script (runs on Proxmox) |
| `.env.example` | Configuration template |
| `.env` | Your configuration (create from .env.example) |
| `QUICK-START.md` | This file |
| `README-COLLECTION.md` | Detailed overview |
| `COLLECTION-GUIDE.md` | Complete reference manual |
## Troubleshooting
### "Cannot connect to Proxmox"
```bash
# Test connection
ping 192.168.1.100
ssh root@192.168.1.100
# If password prompt, set up keys:
ssh-keygen -t ed25519
ssh-copy-id root@192.168.1.100
```
### "PROXMOX_HOST not set"
Edit your `.env` file:
```bash
nano .env
# Set PROXMOX_HOST="your-ip"
```
### "Permission denied"
The scripts might not be executable on Windows filesystems. That's OK! When you run:
```bash
bash collect.sh
```
This explicitly uses bash to execute the script.
### Need More Help?
1. **Quick reference**: `cat README-COLLECTION.md`
2. **Complete guide**: `cat COLLECTION-GUIDE.md`
3. **Script help**: `bash collect-remote.sh --help`
## Security Notes
### What's Sanitized by Default
- ✓ Passwords (replaced with `<REDACTED>`)
- ✓ API tokens (replaced with `<REDACTED>`)
- ✗ IP addresses (kept for documentation)
### Full Sanitization
For exports leaving your network:
```bash
bash collect.sh --sanitize all
```
This will also replace IP addresses with `10.X.X.X`.
### Keep It Secure
```bash
# Store exports securely
chmod 700 exports/
# Use private Git repositories
# Never commit unsanitized exports to public repos
# Encrypt sensitive exports
gpg --symmetric exports/homelab-export-*.tar.gz
```
## Use Cases
### 1. Documentation
"What's running on VM 109?" → Check `configs/vms/109-web-server-01.conf`
### 2. Disaster Recovery
If Proxmox crashes, you have all configurations to rebuild
### 3. Change Tracking
```bash
# Compare this month vs last month
diff -u exports/january/ exports/february/
```
### 4. Infrastructure as Code
Use the collected configs as templates for Terraform/Ansible
### 5. Compliance/Audit
"What was the configuration on date X?" → Check that export
## Advanced Usage
### Different Collection Levels
```bash
# Minimal - just configs
bash collect.sh --level basic
# Standard - configs + status (default)
bash collect.sh --level standard
# Everything - including service configs
bash collect.sh --level full
# Maximum detail
bash collect.sh --level paranoid
```
### Custom Output Location
```bash
# Save to specific directory
bash collect.sh --output ~/backups/homelab
```
### Keep Remote Copy
```bash
# Don't delete from Proxmox after download
bash collect.sh --keep-remote
```
### Verbose Output
```bash
# See detailed progress
bash collect.sh --verbose
```
## Success Indicators
After running, you should see:
```
[✓] SSH connection successful
[✓] Confirmed Proxmox VE installation
[✓] Script uploaded successfully
[✓] Collection completed successfully
[✓] Archive downloaded successfully
[✓] Archive extracted
```
And in your summary:
```
Total items collected: 45+
Total items skipped: 0-5 (normal)
Total errors: 0
```
## What's Next?
1. **Explore your export** - Browse the configs directory
2. **Set up Git** - Version control your infrastructure
3. **Schedule automation** - Weekly/monthly snapshots
4. **Build IaC** - Convert to Terraform/Ansible
5. **Document** - Add notes to the docs/ folder in each export
6. **Share** - Use sanitized exports to get help or show off your setup
## Complete Example Workflow
```bash
# 1. Setup (one-time)
cd /mnt/c/Users/fam1n/Documents/homelab
cp .env.example .env
nano .env # Set PROXMOX_HOST
# 2. Collect
bash collect.sh
# 3. Review
cat exports/homelab-export-*/SUMMARY.md
ls -R exports/homelab-export-*/
# 4. Store
cd exports/homelab-export-*/
git init
git add .
git commit -m "Homelab snapshot $(date +%Y-%m-%d)"
# 5. Automate (on Proxmox)
ssh root@your-proxmox-ip
# Set up cron job (see Automation section)
# 6. Repeat monthly
bash collect.sh --level full
```
## You're All Set!
You now have:
- ✓ Complete infrastructure documentation
- ✓ Automated collection capability
- ✓ Disaster recovery reference
- ✓ Foundation for Infrastructure as Code
- ✓ Change tracking capability
Run `bash collect.sh` anytime to refresh your documentation.
---
**Quick Reference Card:**
```bash
# Basic collection with defaults
bash collect.sh
# Full collection, verbose, sanitized
bash collect.sh --level full --sanitize all --verbose
# Quick snapshot
bash collect.sh --level basic
# Help
bash collect.sh --help
bash collect-remote.sh --help
```
**Need more details?** See `COLLECTION-GUIDE.md` for comprehensive documentation.
**Ready to proceed?** Just run: `bash collect.sh`

521
start-here-docs/SCRIPT-USAGE.md Normal file
View File

@@ -0,0 +1,521 @@
# Homelab Collection Script - Quick Reference
## Overview
The `collect-homelab-config.sh` script performs comprehensive, read-only collection of your Proxmox VE infrastructure configuration and exports it in an organized, documented format.
**Status**: ✅ **Fully Operational** (bugs fixed as of 2025-11-29)
---
## Quick Start
### On Proxmox Host (Direct Execution)
```bash
# Copy script to Proxmox host
scp collect-homelab-config.sh root@192.168.2.100:/tmp/
# SSH to Proxmox host
ssh root@192.168.2.100
# Run with default settings
cd /tmp
bash collect-homelab-config.sh
# Or with verbose output
bash collect-homelab-config.sh --verbose
```
### From Your Workstation (Remote Execution)
```bash
# Upload and execute in one command
scp collect-homelab-config.sh root@192.168.2.100:/tmp/ && \
ssh root@192.168.2.100 'cd /tmp && bash /tmp/collect-homelab-config.sh'
# Download the results
scp root@192.168.2.100:/tmp/homelab-export-*.tar.gz ./
```
---
## Command-Line Options
### Collection Levels
```bash
# Basic: System info + Proxmox/VM/CT configs only
./collect-homelab-config.sh --level basic
# Standard: Basic + storage, network, backup, cluster info (DEFAULT)
./collect-homelab-config.sh --level standard
# Full: Standard + service configs, detailed system state
./collect-homelab-config.sh --level full
# Paranoid: Everything possible (experimental)
./collect-homelab-config.sh --level paranoid
```
### Sanitization Options
```bash
# Sanitize everything (IPs, passwords, tokens)
./collect-homelab-config.sh --sanitize all
# Sanitize only IP addresses
./collect-homelab-config.sh --sanitize ips
# No sanitization (CAUTION: sensitive data will be in clear text)
./collect-homelab-config.sh --sanitize none
# Default: Passwords and tokens sanitized, IPs preserved
```
### Output Control
```bash
# Custom output directory
./collect-homelab-config.sh --output /backup/my-homelab-export
# Disable compression
./collect-homelab-config.sh --no-compress
# Enable compression (default)
./collect-homelab-config.sh --compress
```
### Debugging
```bash
# Verbose output (shows DEBUG messages)
./collect-homelab-config.sh --verbose
# Standard output (INFO/SUCCESS/WARN/ERROR only)
./collect-homelab-config.sh
```
### Combined Examples
```bash
# Full collection with complete sanitization and verbose output
./collect-homelab-config.sh --level full --sanitize all --verbose
# Basic collection to specific directory, no compression
./collect-homelab-config.sh --level basic --output /root/configs --no-compress
# Standard collection with IP sanitization
./collect-homelab-config.sh --sanitize all --verbose
```
---
## What Gets Collected
### ✅ Always Collected (All Levels)
**System Information**:
- Proxmox VE version
- Hostname, kernel, uptime
- CPU, memory, disk information
- LVM configuration (PV/VG/LV)
- Network interfaces and routing
- Listening services
- Installed packages
**Proxmox Configurations**:
- Datacenter settings (`datacenter.cfg`)
- Storage pools (`storage.cfg`)
- Users and permissions (`user.cfg`)
- Authentication keys (`authkey.pub`)
- Firewall rules (if configured)
- Corosync cluster config (if in cluster)
- HA configuration (if configured)
**VM Configurations**:
- All QEMU/KVM VM configs (`/etc/pve/nodes/*/qemu-server/*.conf`)
- VM firewall rules
- Format: `{VMID}-{VM-name}.conf`
**LXC Container Configurations**:
- All LXC container configs (`/etc/pve/nodes/*/lxc/*.conf`)
- Container firewall rules
- Format: `{CTID}-{container-name}.conf`
**Network Configurations**:
- Interface definitions (`/etc/network/interfaces`)
- Additional interface configs (`/etc/network/interfaces.d/`)
- SDN configuration (if configured)
- Hosts file
- DNS resolver config
**Storage Information**:
- Storage status (`pvesm status`)
- ZFS pools and datasets (if ZFS is used)
- NFS exports (if configured)
- Samba configuration (if configured)
- iSCSI initiator config (if configured)
### ➕ Standard Level and Above
**Backup Configurations**:
- Vzdump configuration
- Scheduled backup jobs
- Proxmox Backup Server integration
**Cluster Information**:
- Cluster status and membership
- Resource allocation
- Recent tasks history
**Guest Information**:
- VM and container lists
- Resource usage statistics
- JSON exports for programmatic access
### ➕ Full Level and Above
**Service Configurations**:
- Systemd service status
- Proxmox-specific service states
- pve-cluster
- pvedaemon
- pveproxy
- pvestatd
- pve-firewall
- pvescheduler
---
## Output Structure
```
homelab-export-20251129-141328/
├── README.md # Comprehensive documentation
├── SUMMARY.md # Collection statistics and overview
├── collection.log # Detailed execution log
├── configs/ # Configuration files
│ ├── proxmox/ # Proxmox VE configurations
│ │ ├── datacenter.cfg
│ │ ├── storage.cfg
│ │ ├── user.cfg
│ │ └── authkey.pub
│ ├── vms/ # Virtual machine configs
│ │ ├── 100-docker-hub.conf
│ │ ├── 101-gitlab.conf
│ │ └── ...
│ ├── lxc/ # LXC container configs
│ │ ├── 102-nginx.conf
│ │ ├── 103-netbox.conf
│ │ └── 112-Anytype.conf
│ ├── storage/ # Storage configurations
│ ├── network/ # Network configurations
│ ├── backup/ # Backup job configurations
│ └── services/ # System service configs (full level)
├── exports/ # System state exports
│ ├── system/ # System information
│ │ ├── pve-version.txt
│ │ ├── cpuinfo.txt
│ │ ├── meminfo.txt
│ │ └── ...
│ ├── cluster/ # Cluster status and resources
│ └── guests/ # Guest VM/CT information
├── docs/ # For manual documentation additions
├── scripts/ # For automation scripts
└── diagrams/ # For network diagrams
```
---
## Sanitization Behavior
### Default Sanitization (Passwords + Tokens)
**Patterns Removed**:
- `password=*` → `password=<REDACTED>`
- `passwd=*` → `passwd=<REDACTED>`
- `"password": "*"` → `"password": "<REDACTED>"`
- `token=*` → `token=<REDACTED>`
- `api_key=*` → `api_key=<REDACTED>`
- `secret=*` → `secret=<REDACTED>`
**IP Addresses**: Preserved (not sanitized)
### All Sanitization (--sanitize all)
Everything above PLUS:
- All IPv4 addresses → `10.X.X.X`
### No Sanitization (--sanitize none)
⚠️ **DANGER**: All sensitive data remains in clear text. Use only for:
- Air-gapped environments
- Encrypted storage destinations
- Troubleshooting purposes
---
## Expected Output
### Success Indicators
```
================================================================================
Collection Complete
================================================================================
[✓] Total items collected: 50
[INFO] Total items skipped: 1
[WARN] Total errors: 5
Export Location: ./homelab-export-20251129-141328
Summary Report: ./homelab-export-20251129-141328/SUMMARY.md
Collection Log: ./homelab-export-20251129-141328/collection.log
```
### Typical Statistics
- **Items Collected**: 45-60 (depending on your infrastructure)
- **Items Skipped**: 0-5 (files that don't exist, like domains.cfg)
- **Errors**: 0-10 (warnings for optional configs that don't exist)
- **Archive Size**: 30-100KB (compressed)
- **Execution Time**: 5-15 seconds
### Common Warnings (Non-Critical)
```
[WARN] Failed to copy directory HA configuration from /etc/pve/ha
[WARN] Failed to copy directory Additional interface configs from /etc/network/interfaces.d
[WARN] Failed to copy directory SDN configuration from /etc/pve/sdn
[WARN] Failed to execute: pvecm status (Cluster status)
[WARN] Failed to execute: pvecm nodes (Cluster nodes)
```
These are **expected** if you don't have:
- High Availability (HA) configured
- Additional network interface configs
- Software Defined Networking (SDN)
- Multi-node cluster
---
## Post-Collection Workflow
### 1. Review the Collection
```bash
# Extract the archive
tar -xzf homelab-export-20251129-141328.tar.gz
# Review the summary
cat homelab-export-20251129-141328/SUMMARY.md
# Check for errors
grep -E "\[ERROR\]|\[WARN\]" homelab-export-20251129-141328/collection.log
```
### 2. Verify Sensitive Data
```bash
# Verify passwords are sanitized
grep -r "password=" homelab-export-20251129-141328/configs/
# Should show: password=<REDACTED>
```
### 3. Version Control
```bash
# Initialize git (if not already done)
cd /mnt/c/Users/fam1n/Documents/homelab
git init
# Add the export
git add homelab-export-20251129-141328/
git commit -m "Infrastructure snapshot: 2025-11-29"
# Or just commit the archive
git add homelab-export-20251129-141328.tar.gz
git commit -m "Homelab export archive: 2025-11-29"
```
### 4. Documentation Enhancement
Add custom documentation to the collected export:
```bash
cd homelab-export-20251129-141328
# Add network diagrams
cp ~/network-diagram.png diagrams/
# Add runbooks
cat > docs/disaster-recovery.md <<EOF
# Disaster Recovery Procedures
...
EOF
# Add automation scripts
cp ~/ansible-playbooks/*.yml scripts/
```
### 5. Scheduled Collection
Create a cron job on your Proxmox host:
```bash
# Run collection monthly and keep archives
cat > /etc/cron.d/homelab-export <<'EOF'
# Monthly infrastructure export
0 2 1 * * root cd /backup && /opt/scripts/collect-homelab-config.sh --level standard --output /backup/homelab-export-$(date +\%Y\%m) --compress
EOF
```
---
## Troubleshooting
### Script Stops Prematurely
✅ **FIXED** as of 2025-11-29. If you're still experiencing issues:
1. Ensure you're using the latest version of the script
2. Run with `--verbose` to see detailed progress
3. Check `collection.log` for specific errors
4. Verify you have root permissions: `whoami` should return `root`
### Permission Denied Errors
```bash
# Ensure script is executable
chmod +x collect-homelab-config.sh
# Run as root
sudo bash collect-homelab-config.sh
# or
ssh root@proxmox-host 'bash /tmp/collect-homelab-config.sh'
```
### Missing Commands
The script requires standard Proxmox utilities:
- `pveversion`, `pvesh`, `pvesm`, `pvecm`
- `qm`, `pct`
- `lscpu`, `df`, `lsblk`, `ip`, `ss`
These are all included in a standard Proxmox VE installation.
### Archive Too Large
```bash
# Exclude large log files (manual step after collection)
cd homelab-export-20251129-141328
find . -name "*.log" -size +10M -delete
# Re-compress
cd ..
tar -czf homelab-export-20251129-141328-slim.tar.gz homelab-export-20251129-141328/
```
---
## Security Considerations
### ⚠️ Warning: Sensitive Data
Even with sanitization enabled, the export contains:
- ✅ Network topology and IP addressing
- ✅ Usernames (passwords redacted)
- ✅ Storage paths and mount points
- ✅ VM/CT configurations
- ✅ Installed package lists
### Best Practices
1. **Never commit to public repositories** without `--sanitize all`
2. **Encrypt archives** before cloud storage:
```bash
gpg -c homelab-export-20251129-141328.tar.gz
```
3. **Use private Git repos** (GitLab private, GitHub private)
4. **Restrict file permissions**:
```bash
chmod 600 homelab-export-20251129-141328.tar.gz
```
5. **Audit before sharing**: Always review contents before sharing with others
---
## Integration Examples
### Ansible Playbook
```yaml
---
- name: Collect Proxmox infrastructure state
hosts: proxmox
tasks:
- name: Upload collection script
copy:
src: collect-homelab-config.sh
dest: /tmp/collect-homelab-config.sh
mode: '0755'
- name: Run collection
shell: cd /tmp && bash collect-homelab-config.sh --level full
- name: Download export
fetch:
src: /tmp/homelab-export-{{ ansible_date_time.date }}.tar.gz
dest: ./exports/
flat: yes
```
### Backup Script
```bash
#!/bin/bash
# backup-homelab-config.sh
BACKUP_DIR="/mnt/backup/homelab-configs"
PROXMOX_HOST="192.168.2.100"
# Run collection on Proxmox
ssh root@${PROXMOX_HOST} 'cd /tmp && bash /tmp/collect-homelab-config.sh --level full --sanitize all'
# Download archive
scp root@${PROXMOX_HOST}:/tmp/homelab-export-*.tar.gz ${BACKUP_DIR}/
# Clean up old exports (keep last 12)
cd ${BACKUP_DIR}
ls -t homelab-export-*.tar.gz | tail -n +13 | xargs rm -f
# Cleanup remote
ssh root@${PROXMOX_HOST} 'rm -rf /tmp/homelab-export-*'
```
---
## Files in This Directory
- **collect-homelab-config.sh**: The main collection script (FIXED)
- **BUGFIX-SUMMARY.md**: Detailed technical analysis of bugs and fixes
- **SCRIPT-USAGE.md**: This file - quick reference guide
- **homelab-export-*.tar.gz**: Collected infrastructure exports
- **CLAUDE.md**: Repository context and infrastructure overview
---
## Support
For issues, improvements, or questions:
1. Review BUGFIX-SUMMARY.md for technical details
2. Check collection.log in the export for error details
3. Run with `--verbose` for debugging output
4. Verify you're running the latest fixed version
---
*Script version: 1.0.0 (Bugs fixed: 2025-11-29)*
*Documentation maintained in: /mnt/c/Users/fam1n/Documents/homelab/*

264
start-here-docs/SETUP-COMPLETE.md Normal file
View File

@@ -0,0 +1,264 @@
# Git Setup Complete - Summary
**Date**: November 29, 2025
**Status**: ✅ Repository successfully initialized
**Location**: `/home/jramos/homelab`
---
## What Was Done
### 1. Problem Identified
Your attempt to use git in the Windows filesystem (`/mnt/c/Users/fam1n/Documents/homelab`) failed because:
- Windows NTFS doesn't support POSIX file permissions
- Git requires proper permissions for lock files
- WSL2 translation layer can't bridge this gap for git operations
**Error encountered**: `chmod on .git/config.lock failed: Operation not permitted`
### 2. Solution Implemented
We moved your repository to the **Linux filesystem** where git works properly:
- **Created**: `/home/jramos/homelab` (Linux filesystem)
- **Copied**: All files from Windows location to Linux location
- **Initialized**: Git repository with proper configuration
- **Configured**: `.gitignore` to protect sensitive files
### 3. Files Created
| File | Purpose |
|------|---------|
| `.gitignore` | Prevents sensitive files from being tracked |
| `README.md` | Main repository documentation |
| `GIT-SETUP-GUIDE.md` | Complete guide explaining what we did and why |
| `GIT-QUICK-REFERENCE.md` | Quick command reference for daily use |
| `git-first-commit.sh` | Interactive script to make your first commit |
| `SETUP-COMPLETE.md` | This file |
---
## Repository Status
```
Location: /home/jramos/homelab
Git initialized: Yes ✅
Branch: main
Commits: 0 (no commits yet)
Untracked files: 73
Ignored files: 2 (.env, .claude/settings.local.json)
```
### Protected Files (Ignored by Git)
- `.env` - Your environment configuration with sensitive data
- `.claude/settings.local.json` - Local settings
- All patterns in `.gitignore` (ISOs, disk images, archives, logs, etc.)
### Ready to Track
- All scripts (`.sh` files)
- Documentation (`.md` files)
- `.env.example` (template, safe to share)
- Configuration files
- Collection exports (optional)
---
## How to Access Your Repository
### From WSL2 Terminal
```bash
cd /home/jramos/homelab
```
### From Windows File Explorer
1. Open File Explorer
2. In address bar, type: `\\wsl$\Ubuntu\home\jramos\homelab`
3. Press Enter
4. **Optional**: Right-click folder → "Pin to Quick access" for easy access
### From Windows Command Prompt / PowerShell
```powershell
\\wsl$\Ubuntu\home\jramos\homelab
```
---
## Your Next Steps
### Step 1: Make Your First Commit
**Option A - Use the Helper Script (Recommended for Beginners)**
```bash
cd /home/jramos/homelab
./git-first-commit.sh
```
This interactive script will:
- Set up your git identity (name and email) if needed
- Show you what will be committed
- Create your first commit
- Explain what to do next
**Option B - Manual Method**
```bash
cd /home/jramos/homelab
# Set your identity (one-time setup)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
# Review what will be committed
git status
git diff
# Stage all files
git add .
# Create the commit
git commit -m "Initial commit: Homelab infrastructure repository"
# View your commit
git log
```
### Step 2: Start Using Git Daily
Every time you make changes to your homelab:
```bash
cd /home/jramos/homelab
# After editing files...
git status # See what changed
git diff # See details of changes
git add . # Stage all changes
git commit -m "Description of what you changed"
git log --oneline -5 # View recent commits
```
### Step 3: Learn the Basics
**Essential Reading** (in order):
1. `GIT-QUICK-REFERENCE.md` - Daily commands you'll use
2. `GIT-SETUP-GUIDE.md` - Complete explanation of setup and workflows
3. `README.md` - Repository overview
**Quick Command Reference**:
```bash
git status # What changed?
git diff # Show me the changes
git add . # Stage everything
git commit -m "msg" # Save changes
git log --oneline # Show history
```
---
## What About the Windows Directory?
You have two options:
### Option 1: Keep Both (Recommended)
- **Windows**: `/mnt/c/Users/fam1n/Documents/homelab` - Use for daily work in Windows
- **Linux**: `/home/jramos/homelab` - Git repository for version control
When you make changes in Windows, sync to Linux:
```bash
rsync -av --exclude='.git' /mnt/c/Users/fam1n/Documents/homelab/ /home/jramos/homelab/
cd /home/jramos/homelab
git add .
git commit -m "Updated from Windows"
```
### Option 2: Use Only Linux Directory
- Work exclusively in `/home/jramos/homelab`
- Access via `\\wsl$\Ubuntu\home\jramos\homelab` from Windows
- Archive or delete the old Windows directory
**Recommendation**: Try Option 2 (Linux only) for a week. It's simpler and git will always work.
---
## Common Questions
### Q: Can I still access files from Windows?
**A**: Yes! Use `\\wsl$\Ubuntu\home\jramos\homelab` in File Explorer.
### Q: What if I accidentally edit files in the old Windows location?
**A**: Just copy them to the Linux location using the rsync command above.
### Q: Will my .env file be committed?
**A**: No, it's in `.gitignore` and will be ignored by git. Only `.env.example` is tracked.
### Q: Can I edit files in VS Code or other Windows editors?
**A**: Yes! Open the `\\wsl$\Ubuntu\home\jramos\homelab` directory in any Windows application.
### Q: What if I make a mistake in git?
**A**: Git is very forgiving. See "Emergency Commands" in `GIT-QUICK-REFERENCE.md`.
### Q: Do I need GitHub/GitLab?
**A**: Not for now. This is a local git repository. You can add remote backup later if you want.
---
## Verification Checklist
Before making your first commit, verify:
- [ ] You can navigate to `/home/jramos/homelab` in WSL2
- [ ] `git status` works without errors
- [ ] `.env` is shown as "Ignored" (run `git status --ignored`)
- [ ] `.env.example` is shown as "Untracked" (will be committed)
- [ ] You can access the directory from Windows Explorer
All checks should pass. If not, see `GIT-SETUP-GUIDE.md` troubleshooting section.
---
## Emergency Contacts
| Issue | Solution |
|-------|----------|
| "chmod failed" error | You're in `/mnt/c/...` instead of `/home/...` |
| "not a git repository" | Run `cd /home/jramos/homelab` |
| "Please tell me who you are" | Set git identity with `git config --global user.name` and `user.email` |
| Committed wrong thing | `git reset --soft HEAD~1` (undo last commit, keep changes) |
| Accidentally changed file | `git checkout -- filename` (restore from last commit) |
---
## Summary
**What you have now**:
- ✅ Working git repository in Linux filesystem
- ✅ All files copied and safe
- ✅ Sensitive files protected by `.gitignore`
- ✅ Accessible from both WSL2 and Windows
- ✅ Ready for your first commit
**What to do next**:
1. Run `./git-first-commit.sh` to make your first commit
2. Start tracking changes to your homelab infrastructure
3. Learn git basics using the reference guides
**Why this matters**:
- 📚 Track history of all infrastructure changes
- ⏪ Undo mistakes easily
- 📝 Document why changes were made
- 🔒 Backup your configuration work
- 🧪 Experiment without fear
---
**Congratulations!** Your homelab is now under professional version control. Start committing changes and build up a history of your infrastructure evolution.
For questions or issues, refer to:
- `GIT-SETUP-GUIDE.md` - Detailed explanations
- `GIT-QUICK-REFERENCE.md` - Quick command lookup
- Git documentation: https://git-scm.com/doc
Happy homelabbing!
---
*Setup completed: 2025-11-29*
*Git version: 2.43.0*
*WSL Distribution: Ubuntu*

264
start-here-docs/START-HERE.md Normal file
View File

@@ -0,0 +1,264 @@
# 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