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

Initial commit: Homelab infrastructure repository with automated collection system

Browse Source 
- Added Proxmox VE configuration collection scripts
- Included documentation and quick-start guides
- First infrastructure snapshot from serviceslab (2025-11-29)
- All VM configs (10 VMs) and LXC configs (3 containers)
- Git setup complete with .gitignore protecting sensitive data
This commit is contained in:
Jordan Ramos
2025-11-29 15:55:56 -07:00
commit 4b62fb0a27
75 changed files with 9497 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

404
INDEX.md Normal file
View File

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