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)

```powershell
# 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

```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

```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

```powershell
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)

```powershell
# 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

```powershell
# 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:

```powershell
# 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

```powershell
# 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`