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)

```powershell
# 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:**
```bash
POSTGRES_USER=stellaops
POSTGRES_PASSWORD=StrongPassword123!
POSTGRES_DB=stellaops_platform

VALKEY_PORT=6379
```

**Start the platform:**
```powershell
docker compose -f docker-compose.dev.yaml up -d
```

**Wait for services to be ready (2-3 minutes):**
```powershell
# 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:**
```powershell
docker compose -f docker-compose.dev.yaml ps
```

You should see all services with `State = Up`.

---

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

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

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

**Create `appsettings.Development.json`:**

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

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

```powershell
# 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

```powershell
# 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:
   ```csharp
   // 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:
   ```powershell
   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

```powershell
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:**
```powershell
# 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:**
```powershell
# 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:**
```powershell
# 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:**
```powershell
# 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:**
```powershell
# 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:

```powershell
# 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

```powershell
# 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