shopdb-flask/.claude/skills/agent-deploy-full.md

name, description

name	description
agent-deploy-full	Complete agent deployment workflow - build, test, deploy to VM, verify endpoint reporting

Full Agent Deployment Workflow

Build C# agent and tray, deploy to VM, restart service, and verify endpoint appears in ShopDB UI.

What This Skill Does

End-to-end agent deployment:

1. Build agent and tray executables
2. Test executables can start locally
3. Deploy to VM via SSH
4. Restart Windows service
5. Verify agent reports to API
6. Check endpoint appears in UI
7. Monitor logs for errors

Prerequisites

Before running this workflow:

• Flask API running at https://192.168.100.1:5001
• VM accessible via SSH (192.168.100.10)
• SSH key configured: ~/.ssh/vm_key
• VM users: SupportUser (admin) for service, shopfloor for testing

Workflow

1. Build Agent and Tray

Call existing build skill:

# Invoke /build-agent skill or manually:
cd agent
dotnet publish ShopDbEndpointAgent/ShopDbEndpointAgent.csproj -c Release -o ../publish/agent
dotnet publish ShopDbEndpointAgent.Tray/ShopDbEndpointAgent.Tray.csproj -c Release -o ../publish/tray
cd ..

Verify build:

• publish/agent/shopdbagent.exe exists (~35MB)
• publish/tray/shopdb-endpoint-tray.exe exists (~69MB)
• Both are self-contained (include .NET runtime)

If build fails:

• Check for compilation errors
• Verify .NET SDK installed (dotnet --version)
• Check for missing dependencies

2. Test Locally (Quick Sanity Check)

Test agent can start without crashing:

cd publish/agent
./shopdbagent.exe --help
cd ../..

Expected: Help text shows, no exceptions

Don't run full agent locally - it will try to install as Windows service

3. Stop VM Service

Stop existing service before deploying new version:

ssh -i ~/.ssh/vm_key SupportUser@192.168.100.10 "Stop-Service ShopDBEndpointAgent -ErrorAction SilentlyContinue"

Check status:

ssh -i ~/.ssh/vm_key SupportUser@192.168.100.10 "Get-Service ShopDBEndpointAgent"

Expected: Status = Stopped

4. Deploy to VM

Copy new executables to VM:

# Agent
scp -i ~/.ssh/vm_key -r publish/agent/* SupportUser@192.168.100.10:C:/ProgramData/ShopDB/EndpointAgent/

# Tray
scp -i ~/.ssh/vm_key -r publish/tray/* SupportUser@192.168.100.10:C:/ProgramData/ShopDB/EndpointAgent/

Verify copy:

ssh -i ~/.ssh/vm_key SupportUser@192.168.100.10 "Get-ChildItem C:/ProgramData/ShopDB/EndpointAgent/ -Name"

Should see:

• shopdbagent.exe
• shopdb-endpoint-tray.exe
• Various .dll files

5. Verify Configuration

Check agent configuration in registry:

ssh -i ~/.ssh/vm_key SupportUser@192.168.100.10 "Get-ItemProperty HKLM:\SOFTWARE\GE\ShopDB"

Required settings:

• BaseUrl = https://192.168.100.1:5001
• CollectorKey = shopdb_pat_YOUR_COLLECTOR_KEY_HERE

If missing or wrong:

# Set BaseUrl
ssh -i ~/.ssh/vm_key SupportUser@192.168.100.10 "reg add HKLM\SOFTWARE\GE\ShopDB /v BaseUrl /t REG_SZ /d https://192.168.100.1:5001 /f"

# Set CollectorKey
ssh -i ~/.ssh/vm_key SupportUser@192.168.100.10 "reg add HKLM\SOFTWARE\GE\ShopDB /v CollectorKey /t REG_SZ /d shopdb_pat_YOUR_COLLECTOR_KEY_HERE /f"

6. Start Service

Restart the Windows service:

ssh -i ~/.ssh/vm_key SupportUser@192.168.100.10 "Start-Service ShopDBEndpointAgent"

Verify service started:

ssh -i ~/.ssh/vm_key SupportUser@192.168.100.10 "Get-Service ShopDBEndpointAgent"

Expected: Status = Running

If service won't start:

• Check logs (step 7)
• Verify registry configuration
• Check .NET runtime version compatibility

7. Monitor Logs

Check agent logs for errors:

ssh -i ~/.ssh/vm_key SupportUser@192.168.100.10 "Get-Content C:/ProgramData/ShopDB/EndpointAgent/logs/latest.log -Tail 30"

What to look for:

• "Service started successfully"
• "Connected to API at https://192.168.100.1:5001"
• "Inventory collection started"
• Connection errors
• Authentication failures
• Exceptions

Common issues:

• Connection refused: Flask API not running or firewall blocking
• 401 Unauthorized: CollectorKey mismatch
• Certificate error: Agent not configured to accept self-signed cert

8. Verify API Connection

Check agent made initial connection:

# Check Flask logs for collector POST
docker compose logs api --tail 50 | grep -i "collector\|endpoint"

Expected: POST /api/collectors/heartbeat or similar

9. Check Endpoint in UI

Navigate to endpoints page and verify:

URL: https://192.168.100.1:5001/endpoints

Should see:

• Endpoint with hostname matching VM
• Last seen timestamp recent (< 5 min ago)
• System information populated (OS, IP, etc.)
• Status: Active

If endpoint doesn't appear:

• Wait 2-3 minutes (collection interval)
• Check API logs for POST failures
• Verify agent service running
• Check firewall rules on host

10. Test Tray Application (Optional)

Test system tray app as standard user:

# Login to VM as shopfloor user via RDP
# Start: C:\ProgramData\ShopDB\EndpointAgent\shopdb-endpoint-tray.exe

Expected:

• Tray icon appears in notification area
• Right-click shows menu
• Can open ShopDB link
• No errors in logs

11. Summary Report

[X] Deployment successful:

Agent deployment complete:
[X] Built: agent (35MB), tray (69MB)
[X] Deployed to VM: C:\ProgramData\ShopDB\EndpointAgent\
[X] Service status: Running
[X] Logs: No errors, connected to API
[X] Endpoint visible in UI: DESKTOP-VM01 (192.168.100.10)
[X] Last seen: 2 minutes ago

Deployment successful! Agent is reporting normally.

WARNING: Issues detected:

Agent deployment completed with warnings:
[X] Built and deployed
[X] Service started
[ ] Connection errors in logs (certificate validation)
[ ] Endpoint not appearing in UI

Action needed:
1. Check agent logs: C:\ProgramData\ShopDB\EndpointAgent\logs\latest.log
2. Verify Flask API accessible from VM: curl -k https://192.168.100.1:5001/api/health
3. Check firewall rules allow VM -> host traffic on port 5001

Troubleshooting: See [[agent-deployment]] memory for detailed steps

Troubleshooting

Service won't start:

• Check Windows Event Viewer on VM
• Verify .NET runtime included (self-contained)
• Check for port conflicts (another instance running?)

Connection refused:

• Verify Flask API running: docker compose ps
• Check host firewall: port 5001 open for VM
• Test from VM: curl -k https://192.168.100.1:5001/api/health

401 Unauthorized:

• CollectorKey mismatch between registry and .env
• Check .env: COLLECTOR_API_KEY=shopdb_pat_...
• Verify registry: reg query HKLM\SOFTWARE\GE\ShopDB /v CollectorKey

Endpoint not appearing:

• Wait 5 minutes (collection interval)
• Check API logs for POST /api/collectors/heartbeat
• Verify collector authentication enabled
• Check database: SELECT * FROM endpoints;

Rollback

If deployment fails, rollback to previous version:

# Stop service
ssh -i ~/.ssh/vm_key SupportUser@192.168.100.10 "Stop-Service ShopDBEndpointAgent"

# Restore previous build (if backed up)
# Or redeploy previous version from publish/agent/

# Restart service
ssh -i ~/.ssh/vm_key SupportUser@192.168.100.10 "Start-Service ShopDBEndpointAgent"

Related

• /build-agent - Just build executables
• /production-health - Check overall system health
• agent-deployment - Detailed agent deployment guide
• vm-ssh-access - SSH key setup
• vm-network-access - Firewall configuration
• .claude/setup/VM-USERS.md - VM user accounts