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:

# On Host PC (this machine):
winget install Microsoft.DotNet.SDK.8

Build agent executables:

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:

# On VM:
Expand-Archive C:\path\to\shopdb-agent.zip -DestinationPath C:\ProgramData\ShopDB\EndpointAgent

---

Step 3: Configure Agent (On VM)

Set registry configuration:

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

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:

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

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:

# On host PC:
docker logs flask-shopdb-api-1 | grep -i "collector/endpoints"

---

Troubleshooting

Agent can't reach server

Test connectivity from VM:

# On VM:
Test-NetConnection -ComputerName 172.31.96.1 -Port 5001

If blocked by firewall:

# 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)

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:

# On VM:
Get-ItemProperty -Path 'HKLM:\SOFTWARE\GE\ShopDB' -Name 'CollectorKey'

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

---

Uninstall

# 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)