git.stella-ops.org/docs/QUICKSTART_HYBRID_DEBUG.md

Quick Start: Hybrid Debugging Guide

Goal: Get the full StellaOps platform running in Docker, then debug Scanner.WebService in Visual Studio.

Time Required: 15-20 minutes

Prerequisites Checklist

• Docker Desktop installed and running
• .NET 10 SDK installed (dotnet --version shows 10.0.x)
• Visual Studio 2022 (v17.12+) installed
• Repository cloned to C:\dev\New folder\git.stella-ops.org

---

Step 1: Start Full Platform in Docker (5 minutes)

# Navigate to compose directory
cd "C:\dev\New folder\git.stella-ops.org\deploy\compose"

# Copy environment template
copy env\dev.env.example .env

# Edit .env with your credentials (use Notepad or VS Code)
notepad .env

Minimum required changes in .env:

POSTGRES_USER=stellaops
POSTGRES_PASSWORD=StrongPassword123!
POSTGRES_DB=stellaops_platform

VALKEY_PORT=6379

Start the platform:

docker compose -f docker-compose.dev.yaml up -d

Wait for services to be ready (2-3 minutes):

# Watch logs until services are healthy
docker compose -f docker-compose.dev.yaml logs -f

# Press Ctrl+C to stop watching logs

Verify platform is running:

docker compose -f docker-compose.dev.yaml ps

You should see all services with State = Up.

---

Step 2: Stop Scanner.WebService Container (30 seconds)

# Stop the Scanner.WebService container
docker compose -f docker-compose.dev.yaml stop scanner-web

# Verify it stopped
docker compose -f docker-compose.dev.yaml ps scanner-web
# Should show: State = "exited"

---

Step 3: Configure Scanner for Local Development (2 minutes)

# Navigate to Scanner.WebService project
cd "C:\dev\New folder\git.stella-ops.org\src\Scanner\StellaOps.Scanner.WebService"

Create appsettings.Development.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "StellaOps": "Debug"
    }
  },
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Port=5432;Database=stellaops_platform;Username=stellaops;Password=StrongPassword123!;Include Error Detail=true"
  },
  "Scanner": {
    "Storage": {
      "Driver": "postgres"
    },
    "ArtifactStore": {
      "Driver": "rustfs",
      "Endpoint": "http://localhost:8080/api/v1",
      "Bucket": "scanner-artifacts",
      "TimeoutSeconds": 30
    },
    "Queue": {
      "Broker": "valkey://localhost:6379"
    },
    "Events": {
      "Enabled": false
    }
  },
  "Authority": {
    "Issuer": "https://localhost:8440",
    "BaseUrl": "https://localhost:8440",
    "BypassNetworks": ["127.0.0.1", "::1"]
  }
}

Important: Replace StrongPassword123! with the password you set in .env.

---

Step 4: Open Solution in Visual Studio (1 minute)

# Open solution (from repository root)
cd "C:\dev\New folder\git.stella-ops.org"
start src\StellaOps.sln

In Visual Studio:

1. Wait for solution to load fully (watch bottom-left status bar)
2. In Solution Explorer, navigate to:
   • Scanner folder
   • StellaOps.Scanner.WebService project
3. Right-click StellaOps.Scanner.WebService → "Set as Startup Project"
   • The project name will become bold

---

Step 5: Start Debugging (1 minute)

Press F5 (or click the green "Start" button)

Expected console output:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5210
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7210
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.

Visual Studio should now show:

• Debug toolbar at the top
• Console output in "Output" window
• "Running" indicator on Scanner.WebService project

---

Step 6: Test Your Local Service (2 minutes)

Open a new PowerShell terminal and run:

# Test the health endpoint
curl http://localhost:5210/health

# Test a simple API call (if Swagger is enabled)
# Open browser to: http://localhost:5210/swagger

# Or test with curl
curl -X GET http://localhost:5210/api/catalog

---

Step 7: Set a Breakpoint and Debug (5 minutes)

Find a Controller to Debug

In Visual Studio:

1. Press Ctrl+T (Go to All)
2. Type: ScanController
3. Open the file
4. Find a method like CreateScan or GetScan
5. Click in the left margin (or press F9) to set a breakpoint
   • A red dot should appear

Trigger the Breakpoint

# Make a request that will hit your breakpoint
curl -X POST http://localhost:5210/api/scans `
  -H "Content-Type: application/json" `
  -d '{"imageRef": "alpine:latest"}'

Visual Studio should:

• Pause execution at your breakpoint
• Highlight the current line in yellow
• Show variable values in the "Locals" window

Debug Controls

• F10 - Step Over (execute current line, move to next)
• F11 - Step Into (enter method calls)
• Shift+F11 - Step Out (exit current method)
• F5 - Continue (run until next breakpoint)

Inspect Variables

Hover your mouse over any variable to see its value, or:

• Locals Window: Debug → Windows → Locals
• Watch Window: Debug → Windows → Watch
• Immediate Window: Debug → Windows → Immediate (type expressions and press Enter)

---

Step 8: Make Code Changes with Hot Reload (3 minutes)

Try Hot Reload

1. While debugging (F5 running), modify a string in your code:

   // Before
   return Ok("Scan created");
   
   // After
   return Ok("Scan created successfully!");
   

2. Save the file (Ctrl+S)

3. Visual Studio should show: "Hot Reload succeeded" in the bottom-right

4. Make another request to see the change:

   curl -X POST http://localhost:5210/api/scans `
     -H "Content-Type: application/json" `
     -d '{"imageRef": "alpine:latest"}'
   

Note: Hot Reload works for many changes but not all (e.g., changing method signatures requires a restart).

---

Step 9: Stop Debugging and Return to Docker (1 minute)

Stop Visual Studio Debugger

Press Shift+F5 (or click the red "Stop" button)

Restart Docker Container

cd "C:\dev\New folder\git.stella-ops.org\deploy\compose"

# Start the Scanner.WebService container again
docker compose -f docker-compose.dev.yaml start scanner-web

# Verify it's running
docker compose -f docker-compose.dev.yaml ps scanner-web
# Should show: State = "Up"

---

Common Issues & Quick Fixes

Issue 1: "Port 5432 already in use"

Fix:

# Find what's using the port
netstat -ano | findstr :5432

# Kill the process (replace <PID> with actual process ID)
taskkill /PID <PID> /F

# Or change the port in .env
# POSTGRES_PORT=5433

Issue 2: "Cannot connect to PostgreSQL"

Fix:

# Verify PostgreSQL is running
docker compose -f docker-compose.dev.yaml ps postgres

# Check logs
docker compose -f docker-compose.dev.yaml logs postgres

# Restart PostgreSQL
docker compose -f docker-compose.dev.yaml restart postgres

Issue 3: "Valkey connection refused"

Fix:

# Verify Valkey is running
docker compose -f docker-compose.dev.yaml ps valkey

# Restart Valkey
docker compose -f docker-compose.dev.yaml restart valkey

# Test connectivity
telnet localhost 6379

Issue 4: "RustFS connection failed"

Fix:

# Verify RustFS is running
docker compose -f docker-compose.dev.yaml ps rustfs

# Restart RustFS
docker compose -f docker-compose.dev.yaml restart rustfs

# Test API
curl http://localhost:8080/health

Issue 5: "Build failed in Visual Studio"

Fix:

# Restore NuGet packages
cd "C:\dev\New folder\git.stella-ops.org"
dotnet restore src\StellaOps.sln

# Clean and rebuild
dotnet clean src\StellaOps.sln
dotnet build src\StellaOps.sln

---

Next Steps

Debug Another Service

Repeat the process for any other service:

# Example: Debug Concelier.WebService
cd "C:\dev\New folder\git.stella-ops.org\deploy\compose"
docker compose -f docker-compose.dev.yaml stop concelier

# Create appsettings.Development.json in Concelier project
# Set as startup project in Visual Studio
# Press F5

Debug Multiple Services Together

In Visual Studio:

1. Right-click Solution → Properties
2. Common Properties → Startup Project
3. Select "Multiple startup projects"
4. Set multiple projects to "Start":
   • Scanner.WebService: Start
   • Scanner.Worker: Start
5. Click OK
6. Press F5 to debug both simultaneously

Learn More

• Full Developer Guide: docs/DEVELOPER_ONBOARDING.md
• Architecture: docs/07_HIGH_LEVEL_ARCHITECTURE.md
• Build Commands: CLAUDE.md

---

Cheat Sheet

Essential Docker Commands

# Start all services
docker compose -f docker-compose.dev.yaml up -d

# Stop a specific service
docker compose -f docker-compose.dev.yaml stop <service-name>

# View logs
docker compose -f docker-compose.dev.yaml logs -f <service-name>

# Restart a service
docker compose -f docker-compose.dev.yaml restart <service-name>

# Stop all services
docker compose -f docker-compose.dev.yaml down

# Remove all volumes (DESTRUCTIVE - deletes databases)
docker compose -f docker-compose.dev.yaml down -v

Visual Studio Debug Shortcuts

Action	Shortcut
Start Debugging	F5
Stop Debugging	Shift+F5
Toggle Breakpoint	F9
Step Over	F10
Step Into	F11
Step Out	Shift+F11
Continue	F5

Quick Service Access

Service	URL
Scanner (your debug instance)	http://localhost:5210
PostgreSQL	localhost:5432
Valkey	localhost:6379
RustFS	http://localhost:8080
Authority	https://localhost:8440
NATS (optional)	localhost:4222

---

Happy Debugging! 🚀

For questions or issues, refer to:

• Full Guide: docs/DEVELOPER_ONBOARDING.md
• Troubleshooting Section: See above or full guide
• Architecture Docs: docs/ directory