skystack/QUICKSTART.md

# QEMU VM Manager - Quick Start Guide

Get up and running with QEMU VM Manager in minutes! This guide covers both single-node and distributed P2P modes.

## 🚀 Quick Start (5 minutes)

### 1. Prerequisites Check
```bash
# Check .NET version (requires 8.0+)
dotnet --version

# Check QEMU installation
qemu-system-x86_64 --version

# Check virtualization support
# Windows: Enable Hyper-V in Windows Features
# Linux: Check KVM support with 'lsmod | grep kvm'
# macOS: Check HVF support
```

### 2. Build and Run
```bash
# Clone and build
git clone https://github.com/yourusername/qemu-vm-manager.git
cd qemu-vm-manager
dotnet build

# Run the application
dotnet run --project QemuVmManager.Console
```

### 3. Choose Your Mode
```
=== QEMU VM Manager ===
Choose mode:
1. Single Node Mode (original)
2. P2P Distributed Mode (new)
Enter choice (1 or 2):
```

## 🎯 Single Node Mode

### Basic VM Operations
```bash
# Create a VM
qemu-vm> create my-first-vm
# Follow the interactive prompts

# Import a VM from configuration file
qemu-vm> import examples/sample-vm-config.json my-imported-vm

# Start the VM
qemu-vm> start my-first-vm

# Check status
qemu-vm> status

# Stop the VM
qemu-vm> stop my-first-vm
```

### Performance Monitoring
```bash
# Start monitoring
qemu-vm> monitor start my-first-vm

# View metrics
qemu-vm> metrics my-first-vm

# Stop monitoring
qemu-vm> monitor stop my-first-vm
```

### Disk Management
```bash
# Create a new disk
qemu-vm> disk create ubuntu.qcow2 20GB

# Get disk information
qemu-vm> disk info ubuntu.qcow2

# Resize disk
qemu-vm> disk resize ubuntu.qcow2 40GB
```

### System Diagnostics
```bash
# Run system diagnosis
qemu-vm> diagnose

# View VM configurations
qemu-vm> list

# Get detailed VM info
qemu-vm> status my-first-vm
```

## 🌐 P2P Distributed Mode

### Starting a P2P Node
```bash
# Choose P2P mode (option 2)
# Enter node ID and port
Node ID: node-001
Port: 8080

# Wait for node to start
Starting P2P node...
Node started successfully!
```

### Cluster Management
```bash
# Check cluster status
qemu-vm> cluster status

# List all nodes
qemu-vm> nodes list

# View cluster topology
qemu-vm> cluster info
```

### Distributed VM Operations
```bash
# List VMs across cluster
qemu-vm> vms list

# Start VM on specific node
qemu-vm> start ubuntu-vm --node node-002

# Migrate VM between nodes
qemu-vm> migrate ubuntu-vm node-003

# Stop VM remotely
qemu-vm> stop ubuntu-vm --node node-002
```

### Port Forwarding (Master Node Only)
```bash
# Forward port from external to VM
qemu-vm> forward ubuntu-vm 8080 80

# Check UPnP status
qemu-vm> upnp status

# List active port mappings
qemu-vm> upnp mappings
```

## ⚙️ Configuration Examples

### Basic VM Configuration
```json
{
  "name": "ubuntu-desktop",
  "description": "Ubuntu Desktop VM",
  "cpu": {
    "cores": 4,
    "model": "host"
  },
  "memory": {
    "sizeGB": 8
  },
  "storage": {
    "disks": [
      {
        "path": "ubuntu.qcow2",
        "format": "qcow2",
        "sizeGB": 50,
        "isBoot": true
      }
    ]
  },
  "network": {
    "backend": "user",
    "device": "e1000"
  },
  "display": {
    "type": "gtk",
    "vga": "virtio"
  }
}
```

### P2P Node Configuration
```json
{
  "nodeId": "node-001",
  "port": 8080,
  "discoveryPort": 8081,
  "heartbeatInterval": 5000,
  "electionTimeout": 10000
}
```

## 🔧 Common Commands Reference

### Single Node Commands
| Command | Description | Example |
|---------|-------------|---------|
| `help` | Show all commands | `help` |
| `create` | Create new VM | `create my-vm` |
| `import` | Import VM from config | `import config.json my-vm` |
| `start` | Start VM | `start my-vm` |
| `stop` | Stop VM | `stop my-vm` |
| `status` | Show VM status | `status my-vm` |
| `list` | List all VMs | `list` |
| `delete` | Delete VM | `delete my-vm` |
| `monitor` | Performance monitoring | `monitor start my-vm` |
| `metrics` | Show performance data | `metrics my-vm` |
| `diagnose` | System diagnosis | `diagnose` |

### P2P Commands
| Command | Description | Example |
|---------|-------------|---------|
| `cluster` | Cluster operations | `cluster status` |
| `nodes` | Node management | `nodes list` |
| `vms` | Distributed VM ops | `vms list` |
| `migrate` | Move VM between nodes | `migrate vm-name node-id` |
| `forward` | Port forwarding | `forward vm-name 8080 80` |
| `upnp` | UPnP operations | `upnp status` |

### Disk Commands
| Command | Description | Example |
|---------|-------------|---------|
| `disk create` | Create disk image | `disk create disk.qcow2 20GB` |
| `disk info` | Show disk info | `disk info disk.qcow2` |
| `disk resize` | Resize disk | `disk resize disk.qcow2 40GB` |
| `disk convert` | Convert format | `disk convert disk.img disk.qcow2` |

## 🚨 Troubleshooting

### VM Won't Start
```bash
# Run diagnosis
qemu-vm> diagnose

# Check common issues:
# 1. Hardware virtualization enabled in BIOS
# 2. QEMU in PATH
# 3. Disk images exist
# 4. Sufficient memory/CPU
```

### P2P Connection Issues
```bash
# Check node status
qemu-vm> cluster status

# Verify network connectivity
# Check firewall settings
# Ensure discovery ports are open
```

### Performance Issues
```bash
# Check virtualization type
qemu-vm> diagnose

# Monitor resource usage
qemu-vm> monitor start vm-name
qemu-vm> metrics vm-name

# Consider migration to less loaded node
qemu-vm> migrate vm-name target-node
```

## 📊 Performance Tips

### Hardware Acceleration
- **Enable virtualization in BIOS** (VT-x/AMD-V)
- **Use virtio drivers** when available
- **Monitor performance metrics** regularly

### Network Optimization
- **Use bridge networking** on Linux (when available)
- **Enable UPnP** for automatic port forwarding
- **Monitor network performance** across nodes

### Storage Optimization
- **Use qcow2 format** for better performance
- **Enable disk caching** when appropriate
- **Monitor I/O performance** with metrics

## 🔄 Next Steps

### Advanced Features
1. **Custom VM configurations** - Edit JSON files directly
2. **Performance tuning** - Adjust CPU/memory allocation
3. **Network configuration** - Set up custom network topologies
4. **Backup strategies** - Implement VM backup procedures

### Scaling Your Cluster
1. **Add more nodes** - Expand your P2P network
2. **Load balancing** - Distribute VMs across nodes
3. **High availability** - Set up redundant master nodes
4. **Monitoring** - Implement cluster-wide monitoring

### Integration
1. **CI/CD pipelines** - Automate VM deployment
2. **Monitoring tools** - Integrate with Prometheus/Grafana
3. **Orchestration** - Use with Kubernetes/Docker
4. **API access** - Build custom management tools

## 📚 Additional Resources

- **Full Documentation**: [README.md](README.md)
- **API Reference**: Check source code for detailed API documentation
- **Examples**: See `examples/` directory for sample configurations
- **Issues**: Report bugs on GitHub Issues
- **Discussions**: Join community discussions on GitHub

---

**Need help? Run `diagnose` for system health check or check the troubleshooting section above!**