stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
4602ccc3a3c8f7d8c29330f534def68739ac0e1d
git.stella-ops.org/docs/QUICKSTART_HYBRID_DEBUG.md

10 KiB
Raw Blame History

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:

MONGO_INITDB_ROOT_USERNAME=stellaops
MONGO_INITDB_ROOT_PASSWORD=StrongPassword123!

POSTGRES_USER=stellaops
POSTGRES_PASSWORD=StrongPassword123!

MINIO_ROOT_USER=stellaops
MINIO_ROOT_PASSWORD=StrongPassword123!

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": {
      "Mongo": {
        "ConnectionString": "mongodb://stellaops:StrongPassword123!@localhost:27017"
      }
    },
    "ArtifactStore": {
      "Driver": "rustfs",
      "Endpoint": "http://localhost:8080/api/v1",
      "Bucket": "scanner-artifacts",
      "TimeoutSeconds": 30
    },
    "Queue": {
      "Broker": "nats://localhost:4222"
    },
    "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: "NATS connection refused"

Fix:

# Verify NATS is running
docker compose -f docker-compose.dev.yaml ps nats

# Restart NATS
docker compose -f docker-compose.dev.yaml restart nats

# Test connectivity
telnet localhost 4222

Issue 4: "MongoDB authentication failed"

Fix:

Check that passwords match in .env and appsettings.Development.json:

# Reset MongoDB
docker compose -f docker-compose.dev.yaml stop mongo
docker volume rm compose_mongo-data
docker compose -f docker-compose.dev.yaml up -d mongo

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
MongoDB localhost:27017
MinIO Console http://localhost:9001
RustFS http://localhost:8080
Authority https://localhost:8440

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