From 21fe05f621f2ff8f706908874fb984e1310f06f5 Mon Sep 17 00:00:00 2001
From: Proudlock <270015376@geaerospace.com>
Date: Mon, 7 Sep 2026 01:18:32 -0400
Subject: [PATCH] Add agent installation guide for Hyper-V VM

Configuration for deploying fleet agent on VM that reports to host PC:
- Host IP: 172.31.96.1
- Collector API key included
- Step-by-step build and install instructions
- Network and SSL troubleshooting

Completes the Docker deployment with endpoint monitoring capability.
---
 agent/INSTALL-ON-VM.md | 199 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 199 insertions(+)
 create mode 100644 agent/INSTALL-ON-VM.md

diff --git a/agent/INSTALL-ON-VM.md b/agent/INSTALL-ON-VM.md
new file mode 100644
index 00000000..fa7722b4
--- /dev/null
+++ b/agent/INSTALL-ON-VM.md
@@ -0,0 +1,199 @@
+# 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)