shopdb-flask/.claude/setup/VM-SNAPSHOT-GUIDE.md

VM Snapshot Management for ShopDB Testing

Guide for creating and managing Hyper-V VM snapshots for agent testing with Claude Code MCP integration.

---

Why Snapshots Matter

Snapshots enable rapid iteration:

• Test agent installation/uninstallation
• Revert to clean state after failed deployments
• Test different configurations without rebuilding VM
• Capture known-good states (clean install, agent installed, agent configured)
• Compare behavior across configurations

With MCP integration, Claude can:

• Deploy agent to VM via SSH
• Run tests and check results
• Revert VM to snapshot if test fails
• Retry with different configuration
• All automated through conversation

---

Snapshot Strategy

Baseline Snapshots (Create Once)

Snapshot Name	Description	When to Use
Clean-Install	Fresh Windows 11, no software	Starting from scratch
Docker-Ready	Docker Desktop installed and running	Testing Docker deployments
SSH-Enabled	OpenSSH server configured	Testing SSH/MCP connections
ShopDB-Deployed	ShopDB running in Docker	Testing agent integration

Testing Snapshots (Create/Delete Frequently)

Snapshot Name	Description	When to Use
Agent-Installed	Agent service installed but not configured	Testing agent configuration changes
Agent-Running	Agent fully configured and running	Testing plugin changes
Before-Test-{name}	State before specific test run	Easy rollback after test

---

Creating Snapshots

Method 1: PowerShell (Recommended for Automation)

# From host PC (requires Administrator privileges)

# Create snapshot
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Clean-Install"

# Create snapshot with description
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Agent-Installed" `
  -Notes "ShopDB agent v1.2.3 installed, not yet configured"

# List all snapshots
Get-VMSnapshot -VMName "ShopDB-Test-VM" | Select-Object Name, CreationTime, ParentSnapshotName | Format-Table

# Show snapshot tree
Get-VMSnapshot -VMName "ShopDB-Test-VM" | Format-Table -Property Name, ParentSnapshotName, CreationTime

Method 2: Hyper-V Manager GUI

1. Open Hyper-V Manager
2. Select VM in left pane
3. Right-click VM -> Checkpoint
4. Enter snapshot name in dialog
5. Click OK

Method 3: Via Claude Code (When MCP VM Server is Connected)

You: "Create a snapshot of the VM named 'Before-Agent-Install'"

Claude: [Uses MCP SSH to run PowerShell command on host]

---

Restoring Snapshots

Method 1: PowerShell

# Restore to specific snapshot
Restore-VMSnapshot -Name "Clean-Install" -VMName "ShopDB-Test-VM" -Confirm:$false

# Restore to most recent snapshot
$latest = Get-VMSnapshot -VMName "ShopDB-Test-VM" | Sort-Object CreationTime -Descending | Select-Object -First 1
Restore-VMSnapshot -VMSnapshot $latest -Confirm:$false

Method 2: Hyper-V Manager GUI

1. Open Hyper-V Manager
2. Select VM in left pane
3. In bottom Checkpoints pane, right-click desired snapshot
4. Select Apply
5. Choose:
   • Apply (restore without creating new snapshot)
   • Apply and Create Checkpoint (save current state first)

Method 3: Via Claude Code

You: "Revert VM to 'Clean-Install' snapshot"

Claude: [Uses MCP to restore snapshot via PowerShell]

---

Deleting Snapshots

PowerShell

# Delete specific snapshot
Remove-VMSnapshot -VMName "ShopDB-Test-VM" -Name "Before-Test-2024-09-09"

# Delete all snapshots (WARNING: cannot undo)
Get-VMSnapshot -VMName "ShopDB-Test-VM" | Remove-VMSnapshot -Confirm:$false

# Delete snapshots older than 30 days
$cutoff = (Get-Date).AddDays(-30)
Get-VMSnapshot -VMName "ShopDB-Test-VM" | 
  Where-Object { $_.CreationTime -lt $cutoff } | 
  Remove-VMSnapshot -Confirm:$false

Notes on Deletion:

• Deleting a snapshot merges its changes into parent snapshot
• Does not delete the VM state that snapshot represents
• Frees up disk space on host

---

Snapshot Workflows with Claude Code

Example 1: Clean Agent Installation Test

You: "Test agent installation from scratch"

Claude:
1. [Restore VM to "Docker-Ready" snapshot]
2. [SSH to VM: Copy agent installer]
3. [SSH to VM: Run installer]
4. [SSH to VM: Verify service installed]
5. [MySQL: Check no endpoint records exist yet]
6. [SSH to VM: Start agent service]
7. [MySQL: Wait for endpoint to register]
8. [SSH to VM: Check agent logs for errors]
9. Result: Agent installed successfully, endpoint registered

You: "Something failed, revert and try again"

Claude:
1. [Restore VM to "Docker-Ready" snapshot]
2. [Retry with adjusted configuration]

Example 2: Test Plugin Changes

You: "Deploy new plugin version and test on VM"

Claude:
1. [Create snapshot "Before-Plugin-Update"]
2. [Build frontend with new plugin]
3. [Rebuild Docker image]
4. [SSH to VM: Pull new image]
5. [SSH to VM: Restart containers]
6. [Browser MCP: Open https://192.168.100.10:5001]
7. [Test new plugin functionality]
8. Result: Plugin works! (or: Plugin broken, reverting...)

Example 3: Automated Regression Testing

You: "Run full regression test suite on VM"

Claude:
1. [Restore to "ShopDB-Deployed" snapshot]
2. [SSH: Install agent]
3. [MySQL: Create test data (fleet alerts, operator reports)]
4. [SSH: Verify agent receives alerts]
5. [SSH: Submit test operator report]
6. [MySQL: Verify report data stored correctly]
7. [SSH: Capture screenshots of tray notifications]
8. [SSH: Check agent logs for errors]
9. [Restore to "ShopDB-Deployed" (clean up test data)]
10. Result: All tests passed

---

Snapshot Storage and Performance

Disk Space Considerations

• Each snapshot stores incremental changes from parent
• First snapshot after large change (OS update) will be large
• Multiple small snapshots are more efficient than few large ones
• Deleting snapshots merges changes (may take time for large snapshots)

Check Snapshot Disk Usage

Get-VMSnapshot -VMName "ShopDB-Test-VM" | 
  ForEach-Object {
    $path = $_.Path
    $size = (Get-ChildItem -Path $path -Recurse | Measure-Object -Property Length -Sum).Sum / 1GB
    [PSCustomObject]@{
      Name = $_.Name
      Created = $_.CreationTime
      SizeGB = [math]::Round($size, 2)
    }
  } | Format-Table

Performance Impact

• Snapshots slow down VM I/O (each write goes to differencing disk)
• For long-running VMs, merge old snapshots periodically
• Keep snapshot chain depth under 10 for best performance
• Delete snapshots after merging changes into base disk

---

Recommended Snapshot Schedule

Initial Setup (Do Once)

# 1. Clean Windows 11 install
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Clean-Install"

# 2. Install Docker Desktop, reboot, then:
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Docker-Ready"

# 3. Enable SSH (run enable-vm-ssh.ps1 on VM), then:
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "SSH-Enabled"

# 4. Deploy ShopDB (run deploy-to-vm.ps1), then:
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "ShopDB-Deployed"

During Development

# Before risky changes
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Before-$(Get-Date -Format 'yyyyMMdd-HHmm')"

# After successful test
Remove-VMSnapshot -VMName "ShopDB-Test-VM" -Name "Before-*" -Confirm:$false

# Weekly: Clean up old test snapshots
Get-VMSnapshot -VMName "ShopDB-Test-VM" | 
  Where-Object { $_.Name -like "Before-*" -and $_.CreationTime -lt (Get-Date).AddDays(-7) } |
  Remove-VMSnapshot -Confirm:$false

---

Integration with MCP Test Script

The test-mcp-servers.ps1 script checks for snapshots:

# Run test script
.\\.claude\test-mcp-servers.ps1

# Output includes snapshot status:
# [7/7] Checking VM snapshots...
#   OK: Found 4 snapshot(s)
#     - ShopDB-Test-VM: Clean-Install (2024-09-08 10:30)
#     - ShopDB-Test-VM: Docker-Ready (2024-09-08 11:45)
#     - ShopDB-Test-VM: SSH-Enabled (2024-09-08 12:15)
#     - ShopDB-Test-VM: ShopDB-Deployed (2024-09-09 09:00)

---

Troubleshooting

Cannot Create Snapshot

Error: "The operation cannot be performed while the virtual machine is running"

• Some VM configurations prevent live snapshots
• Fix: Shut down VM first, then create snapshot

Error: "Not enough disk space"

• Snapshots require free space on host drive
• Fix: Delete old snapshots or increase host drive space

Cannot Restore Snapshot

Error: "The checkpoint operation failed"

• VM may be in saved state
• Fix: Shut down VM completely, then restore

Snapshot Chain Too Deep

Error: "Performance degraded due to snapshot chain"

• Too many snapshots slow down VM I/O
• Fix: Merge snapshots by deleting intermediate ones

---

Quick Reference

# Create snapshot
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "MySnapshot"

# List snapshots
Get-VMSnapshot -VMName "ShopDB-Test-VM"

# Restore snapshot
Restore-VMSnapshot -Name "MySnapshot" -VMName "ShopDB-Test-VM" -Confirm:$false

# Delete snapshot
Remove-VMSnapshot -Name "MySnapshot" -VMName "ShopDB-Test-VM"

# Delete all snapshots
Get-VMSnapshot -VMName "ShopDB-Test-VM" | Remove-VMSnapshot -Confirm:$false

# Export VM (with snapshots)
Export-VM -Name "ShopDB-Test-VM" -Path "C:\VM-Backups"

# Get snapshot disk usage
Get-VMSnapshot -VMName "ShopDB-Test-VM" | 
  Select-Object Name, @{N='SizeMB';E={(Get-ChildItem $_.Path -Recurse | Measure-Object Length -Sum).Sum / 1MB}}

---

Next Steps

1. Create baseline snapshots using recommended schedule
2. Test snapshot restore to verify it works
3. Run test-mcp-servers.ps1 to verify MCP integration
4. Practice snapshot workflow with Claude Code
5. Set up automated snapshot cleanup script for weekly maintenance

---

Related Documentation

• Setup SSH: .claude/setup-vm-ssh.md
• Test MCP Servers: .claude/test-mcp-servers.ps1
• Deploy to VM: DEPLOY-TO-VM.md
• VM Connectivity: test-vm-connectivity.ps1