shopdb-flask/agent/INSTALL-ON-VM.md

# Install ShopDB Agent on Hyper-V VM

This guide shows how to install the fleet agent on your Hyper-V VM to report back to ShopDB running on the host PC.

## Configuration for Your Setup

**ShopDB Server (Host PC):**
- URL: `https://172.31.96.1:5001`
- Collector API Key: `shopdb_pat_b4a3fe2a01abc6bc1cb685280e65a8c35d52ec43`

**VM Network:**
- VM can reach host at: `172.31.96.1`
- Host's Hyper-V virtual adapter IP

---

## Step 1: Build the Agent (On Host PC)

**Install .NET SDK first:**
```powershell
# On Host PC (this machine):
winget install Microsoft.DotNet.SDK.8
```

**Build agent executables:**
```powershell
cd C:\Users\270015376\Documents\github\flask-shopdb\agent

# Build service
dotnet publish ShopDbEndpointAgent -c Release -r win-x64 --self-contained -o C:\temp\shopdb-agent

# Build tray app (optional)
dotnet publish ShopDbEndpointAgent.Tray -c Release -r win-x64 --self-contained -o C:\temp\shopdb-agent-tray

# Package for VM
Compress-Archive -Path C:\temp\shopdb-agent -DestinationPath C:\temp\shopdb-agent.zip
```

---

## Step 2: Copy to VM

**Copy the ZIP to your VM:**
- Via RDP shared folder
- Via network share
- Via USB

**Extract on VM:**
```powershell
# On VM:
Expand-Archive C:\path\to\shopdb-agent.zip -DestinationPath C:\ProgramData\ShopDB\EndpointAgent
```

---

## Step 3: Configure Agent (On VM)

**Set registry configuration:**
```powershell
# Run as Administrator on VM:
New-Item -Path 'HKLM:\SOFTWARE\GE\ShopDB' -Force | Out-Null

# Point to HOST PC's IP (not localhost!)
Set-ItemProperty -Path 'HKLM:\SOFTWARE\GE\ShopDB' -Name 'BaseUrl' -Value 'https://172.31.96.1:5001'

# Use the collector key
Set-ItemProperty -Path 'HKLM:\SOFTWARE\GE\ShopDB' -Name 'CollectorKey' -Value 'shopdb_pat_b4a3fe2a01abc6bc1cb685280e65a8c35d52ec43'
```

---

## Step 4: Test Agent (On VM)

**Test one report:**
```powershell
cd C:\ProgramData\ShopDB\EndpointAgent
.\shopdb-endpoint-agent.exe --once
```

**Expected output:**
```
[INFO] Agent starting...
[INFO] Collecting endpoint state...
[INFO] Reporting to https://172.31.96.1:5001/api/collector/endpoints
[INFO] Report successful
```

**If you see SSL certificate errors:**
The self-signed cert will cause warnings. You can either:
- Ignore them (agent still works)
- Or use HTTP (not recommended): `http://172.31.96.1:5001`

---

## Step 5: Install as Service (On VM)

**Create Windows service:**
```powershell
# Run as Administrator on VM:
sc.exe create "ShopDBEndpointAgent" `
  binPath= "C:\ProgramData\ShopDB\EndpointAgent\shopdb-endpoint-agent.exe" `
  start= auto `
  DisplayName= "ShopDB Endpoint Agent"

sc.exe description "ShopDBEndpointAgent" "Reports endpoint telemetry to ShopDB server."

# Start the service
sc.exe start "ShopDBEndpointAgent"
```

**Check service status:**
```powershell
Get-Service ShopDBEndpointAgent
```

---

## Step 6: Verify on Host PC

**Check ShopDB received the report:**

1. Open: `https://localhost:5001/computers`
2. Look for your VM's hostname
3. Click on it to see endpoint data

**Or check logs:**
```bash
# On host PC:
docker logs flask-shopdb-api-1 | grep -i "collector/endpoints"
```

---

## Troubleshooting

### Agent can't reach server

**Test connectivity from VM:**
```powershell
# On VM:
Test-NetConnection -ComputerName 172.31.96.1 -Port 5001
```

**If blocked by firewall:**
```powershell
# On Host PC, allow inbound:
New-NetFirewallRule -DisplayName "ShopDB API" -Direction Inbound -LocalPort 5001 -Protocol TCP -Action Allow
```

### SSL certificate errors

The agent works even with self-signed cert warnings. To eliminate them:

**Option 1: Use HTTP (dev only)**
```powershell
Set-ItemProperty -Path 'HKLM:\SOFTWARE\GE\ShopDB' -Name 'BaseUrl' -Value 'http://172.31.96.1:5001'
```

**Option 2: Trust the cert**
- Export cert from host
- Import to VM's Trusted Root

### Agent reports but PC doesn't appear

**Check collector key matches:**
```powershell
# On VM:
Get-ItemProperty -Path 'HKLM:\SOFTWARE\GE\ShopDB' -Name 'CollectorKey'

# Should match what's in ShopDB .env:
# shopdb_pat_b4a3fe2a01abc6bc1cb685280e65a8c35d52ec43
```

---

## Uninstall

```powershell
# Stop and remove service
sc.exe stop "ShopDBEndpointAgent"
sc.exe delete "ShopDBEndpointAgent"

# Remove files
Remove-Item -Recurse C:\ProgramData\ShopDB\EndpointAgent

# Remove registry
Remove-Item -Path 'HKLM:\SOFTWARE\GE\ShopDB' -Recurse
```

---

## Quick Reference

**Host IP:** `172.31.96.1`  
**ShopDB URL:** `https://172.31.96.1:5001`  
**Collector Key:** `shopdb_pat_b4a3fe2a01abc6bc1cb685280e65a8c35d52ec43`  
**Agent Location:** `C:\ProgramData\ShopDB\EndpointAgent\`  
**Service Name:** `ShopDBEndpointAgent`  
**Report Interval:** 15 minutes (configurable in appsettings.json)