Refactor code structure for improved readability and maintainability; optimize performance in key functions.
This commit is contained in:
master
439
docs/QUICKSTART_HYBRID_DEBUG.md
Normal file
439
docs/QUICKSTART_HYBRID_DEBUG.md
Normal file
@@ -0,0 +1,439 @@
|
||||
# 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
|
||||
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:**
|
||||
```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": {
|
||||
"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)
|
||||
|
||||
```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: "NATS connection refused"
|
||||
|
||||
**Fix:**
|
||||
```powershell
|
||||
# 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`:
|
||||
|
||||
```powershell
|
||||
# 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:**
|
||||
```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` |
|
||||
| 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
|
||||
Reference in New Issue
Block a user