claude-configs/skills/proxmox/docs/README-MIGRATION.md

VM to LXC Migration Tools - Quick Start

Complete toolkit for migrating Docker-based VMs to LXC containers.

📋 What You Get

Estimated Benefits for Your Infrastructure:

• ✅ 8.7GB+ RAM savings (conservative estimate)
• ✅ 11 VMs ready to migrate to LXC
• ✅ 2-5 second startup vs 30-60 second VM boot
• ✅ Better performance for databases and Docker hosts
• ✅ Same functionality with lower overhead

🚀 Quick Start

Step 1: Analyze Your VMs

cd ~/.claude/skills/proxmox/scripts
python3 migrate_vm_to_lxc.py batch-analyze

Output shows:

• ✅ Excellent candidates (ready to migrate)
• 🟢 Good candidates (migrate with care)
• 🟡 Conditional candidates (evaluate first)
• ❌ Poor candidates (keep as VM)

Step 2: Create Docker LXC Template

python3 create_docker_lxc_template.py --id 9001 --name docker-lxc-template

This creates a reusable template with Docker pre-installed.

Step 3: Plan Your First Migration

Start with low-risk VM (e.g., docker-unused or docker-pittsburgh):

python3 migrate_vm_to_lxc.py plan --vmid 117 --ctid 217 --ip 10.10.0.217

This generates a detailed migration plan with step-by-step instructions.

Step 4: Follow the Migration Guide

See lxc_migration_guide.md for complete walkthrough.

Step 5: Use the Checklist

Follow migration_checklist.md to validate each step.

---

📁 Files & Tools

Scripts

• migrate_vm_to_lxc.py - Analysis and planning tool

  • analyze --vmid X - Analyze single VM
  • plan --vmid X --ctid Y - Generate migration plan
  • batch-analyze - Analyze all VMs

• create_docker_lxc_template.py - Template creation wizard

  • Creates Docker-ready LXC template
  • Configures nesting for Docker support
  • Interactive setup process

Documentation

• lxc_migration_guide.md - Complete migration guide

  • Phase-by-phase instructions
  • Detailed examples
  • Rollback procedures
  • Troubleshooting

• migration_checklist.md - Validation checklist

  • 19 phases of checks
  • Pre-migration preparation
  • Post-migration validation
  • Success criteria

• README-MIGRATION.md - This file (quick start)

Python Library

Enhanced proxmox_client.py with full LXC management:

• Container creation and cloning
• Docker-specific configuration
• Snapshot management
• Resource monitoring
• Status tracking

---

🎯 Your Migration Candidates

Based on real analysis of your infrastructure:

✅ High Priority (Excellent Candidates)

Docker Hosts (Safe, Big Wins):

1. docker-unused (VM 117) - ~1.2GB savings - Start here!
2. docker-home-servers (VM 116) - ~250MB savings
3. docker-pittsburgh (VM 114) - ~490MB savings
4. docker-vpn (VM 105) - ~680MB savings
5. docker-home (VM 106) - ~440MB savings
6. docker-7days (VM 111) - ~50MB savings
7. docker-sba (VM 115) - ~1.1GB savings (high memory!)

Application Servers: 8. discord-bots (VM 110) - ~480MB savings 9. databases-bots (VM 112) - ~2.2GB savings (biggest win!)

⚠️ Special Considerations

Keep as VM (Don't Migrate):

• ❌ docker-tdarr (VM 113) - Needs GPU passthrough
• ❌ 7d-solo, 7d-staci, 7d-wotw (VMs 101, 102, 104) - Game servers
• 🟡 plex (VM 107) - Only if CPU transcoding

Templates:

• 📝 docker-template (VM 103) - Keep VM template, create LXC template too
• 📝 ubuntu-template (VM 100) - Keep as-is

---

🗓️ Recommended Migration Schedule

Week 1: Test & Learn

• Create Docker LXC template (9001)
• Migrate docker-unused (117 → 217)
• Validate for 48-72 hours
• Refine process based on learnings

Week 2-3: Low-Impact Docker Hosts

• Migrate docker-pittsburgh (114 → 214)
• Migrate docker-home-servers (116 → 216)
• Migrate docker-vpn (105 → 205)

Week 4-5: Higher-Value Targets

• Migrate docker-sba (115 → 215) - High memory usage!
• Migrate docker-home (106 → 206)
• Migrate docker-7days (111 → 211)

Week 6: Application Servers

• Migrate discord-bots (110 → 210)
• Migrate databases-bots (112 → 212) - Backup first!

Week 7+: Conditional

• Evaluate Plex transcoding method
• If CPU only → migrate (107 → 207)
• If GPU → keep as VM

Total Timeline: 6-8 weeks for safe, validated migrations

---

💡 Key Tips

Before Starting

1. Create VM snapshot before every migration
2. Backup Docker configs before shutting down VM
3. Document running containers and their status
4. Plan static IPs for LXC containers (can match VM IPs)
5. Schedule during low-traffic periods

During Migration

1. One at a time - Don't rush!
2. Follow the checklist - Every phase matters
3. Validate thoroughly - 24-48 hours minimum
4. Monitor resources - Watch for memory/CPU issues
5. Keep VM available - Don't delete for 1-2 weeks

After Migration

1. Compare performance to VM baseline
2. Optimize resources after monitoring actual usage
3. Update documentation - IPs, configs, runbooks
4. Share learnings - Help future migrations
5. Celebrate wins! 🎉

---

❓ Common Questions

Q: Will Docker containers work exactly the same in LXC? A: Yes! With nesting=1,keyctl=1 features enabled, Docker works identically. Your docker-compose files need zero changes.

Q: Can I use static IPs with LXC? A: Absolutely! LXCs support static IPs just like VMs. You can even keep the same IPs during migration.

Q: What if something goes wrong? A: That's why we snapshot the VM first! Stop the LXC, start the VM, and you're back to working state instantly.

Q: How long does each migration take? A: First migration: 2-4 hours (learning process). Subsequent migrations: 30-60 minutes once familiar with the process.

Q: Will my reverse proxy (NPM/Traefik) configs change? A: If you keep the same IP address, no changes needed! Otherwise, just update the IP in your proxy configuration.

Q: Can I rollback after deleting the VM? A: Only if you kept a backup/snapshot! That's why we recommend keeping VMs for 1-2 weeks before deletion.

Q: What about networking - macvlan, bridge, etc.? A: All Docker networking modes work in LXC. Your current port mapping setup will work identically.

---

🆘 Getting Help

If You Get Stuck

1. Check the migration guide: lxc_migration_guide.md - Common Issues & Solutions section

2. Review the checklist: migration_checklist.md - Validation steps

3. Analyze the VM:

   python3 migrate_vm_to_lxc.py analyze --vmid <id>
   

4. Ask Jarvis: I can help troubleshoot specific issues!

Rollback is Safe

If anything goes wrong:

# Stop LXC
pct stop <ctid>

# Start original VM
qm start <vmid>

# Validate VM services
ssh cal@<vm-ip> 'docker ps'

Your VM snapshot ensures you can always go back!

---

📊 Track Your Progress

Create a simple spreadsheet:

VM	Status	Date Started	Date Completed	Savings	Issues
117	✅ Complete	2025-01-15	2025-01-17	1.2GB	None
114	🔄 In Progress	2025-01-22	-	-	-
116	📅 Planned	-	-	-	-

Watch your RAM savings grow!

---

🎯 Success Metrics

You'll know migration is successful when:

• ✅ All services running and accessible
• ✅ Performance equal to or better than VM
• ✅ Resource usage 10-20% lower than VM
• ✅ 24-48 hours of stable operation
• ✅ No errors in logs
• ✅ Faster startup times (2-5 sec vs 30-60 sec)

Program success:

• ✅ 8+ VMs migrated successfully
• ✅ 8-20GB+ RAM freed up
• ✅ All services stable
• ✅ Team comfortable with LXC operations
• ✅ Documentation complete

---

🔗 Additional Resources

Within This Skill

• ../README.md - Main Proxmox skill documentation
• ../SKILL.md - Quick reference for all operations
• ../proxmox_client.py - Python library with full API
• ../examples/ - Working code examples

External Resources

• Proxmox LXC Documentation
• Docker in LXC Best Practices
• LXC vs VM Comparison

---

🎉 Ready to Start!

You have everything you need for a successful migration:

• ✅ Analysis tools
• ✅ Migration scripts
• ✅ Comprehensive guides
• ✅ Validation checklists
• ✅ Real infrastructure analysis
• ✅ Rollback procedures

Recommendation: Start with docker-unused (VM 117) as your test migration. Low risk, good savings, and builds confidence for the rest!

# Your first command:
python3 migrate_vm_to_lxc.py analyze --vmid 117

Good luck! 🚀

---

Document Version: 1.0 Last Updated: 2025-01-11 For: Cal's Home Lab Proxmox Infrastructure Maintained By: Jarvis PAI System