stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

part #2

Browse Source
This commit is contained in:
master
2026-02-04 19:59:20 +02:00
parent 557feefdc3
commit 5548cf83bf
1479 changed files with 53557 additions and 40339 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
docs/DEVELOPER_ONBOARDING.md
View File

@@ -57,6 +57,8 @@ StellaOps is a deterministic, offline-first SBOM + VEX platform built as a micro
---
## Prerequisites
> **Looking for a quick setup checklist?** See [`docs/dev/DEV_ENVIRONMENT_SETUP.md`](dev/DEV_ENVIRONMENT_SETUP.md) for a streamlined, copy-paste-friendly guide covering prerequisites, hosts file, infrastructure, builds, and Docker images.
### Required Software
1. **Docker Desktop** (Windows/Mac) or **Docker Engine + Docker Compose** (Linux)
@@ -67,12 +69,17 @@ StellaOps is a deterministic, offline-first SBOM + VEX platform built as a micro
- Download: https://dotnet.microsoft.com/download/dotnet/10.0
- Verify: `dotnet --version` (should show 10.0.x)
3. **Visual Studio 2022** (v17.12+) or **Visual Studio Code**
3. **Node.js** (for Angular frontend)
- Version: ^20.19.0 || ^22.12.0 || ^24.0.0 (see `src/Web/StellaOps.Web/package.json` engines)
- npm: >=10.2.0
- Verify: `node --version` / `npm --version`
4. **Visual Studio 2022** (v17.12+) or **Visual Studio Code**
- Workload: ASP.NET and web development
- Workload: .NET desktop development
- Extension (VS Code): C# Dev Kit
4. **Git**
5. **Git**
- Version: 2.30+ recommended
### Optional Tools
@@ -104,8 +111,8 @@ cd git.stella-ops.org
```bash
# Copy the development environment template
cd deploy\compose
copy env\dev.env.example .env
cd devops\compose
copy env\stellaops.env.example .env
# Edit .env with your preferred text editor
notepad .env
@@ -119,13 +126,13 @@ notepad .env
### Step 3: Start the Full Platform
```bash
# From deploy/compose directory
docker compose -f docker-compose.dev.yaml up -d
# From devops/compose directory
docker compose -f docker-compose.dev.yml up -d
```
**This will start all infrastructure and services:**
- PostgreSQL v16+ (port 5432) - Primary database for all services
- Valkey 8.0 (port 6379) - Cache, DPoP nonces, event streams, rate limiting
- PostgreSQL 18.1 (port 5432) - Primary database for all services
- Valkey 9.0.1 (port 6379) - Cache, DPoP nonces, event streams, rate limiting
- RustFS (port 8080) - S3-compatible object storage for artifacts/SBOMs
- Authority (port 8440) - OAuth2/OIDC authentication
- Signer (port 8441) - Cryptographic signing
@@ -138,15 +145,15 @@ docker compose -f docker-compose.dev.yaml up -d
```bash
# Check all services are up
docker compose -f docker-compose.dev.yaml ps
docker compose -f docker-compose.dev.yml ps
# Check logs for a specific service
docker compose -f docker-compose.dev.yaml logs -f scanner-web
docker compose -f docker-compose.dev.yml logs -f scanner-web
# Check infrastructure health
docker compose -f docker-compose.dev.yaml logs postgres
docker compose -f docker-compose.dev.yaml logs valkey
docker compose -f docker-compose.dev.yaml logs rustfs
docker compose -f docker-compose.dev.yml logs postgres
docker compose -f docker-compose.dev.yml logs valkey
docker compose -f docker-compose.dev.yml logs rustfs
```
### Step 5: Access the Platform
@@ -176,7 +183,7 @@ Related references:
Service-specific debugging guidance lives with each module to avoid stale, copy-pasted configuration examples.
Generic workflow:
1. Stop the service container in `deploy/compose` (for example: `docker compose -f docker-compose.dev.yaml stop <service>`).
1. Stop the service container in `devops/compose` (for example: `docker compose -f docker-compose.dev.yml stop <service>`).
2. Run the service locally under a debugger.
3. Update dependent services to call `host.docker.internal:<port>` (or your host IP) and restart them.
4. Use the module operations docs for required env vars, auth scopes, and health checks.
@@ -315,11 +322,11 @@ STELLAOPS_SCANNER__QUEUE__BROKER=nats://localhost:4222
```bash
# 1. Start full platform
cd deploy\compose
docker compose -f docker-compose.dev.yaml up -d
cd devops\compose
docker compose -f docker-compose.dev.yml up -d
# 2. Stop the service you want to debug
docker compose -f docker-compose.dev.yaml stop scanner-web
docker compose -f docker-compose.dev.yml stop scanner-web
# 3. Open Visual Studio
cd C:\dev\New folder\git.stella-ops.org
@@ -331,7 +338,7 @@ start src\Scanner\StellaOps.Scanner.sln
curl -X POST http://localhost:5210/api/scans -H "Content-Type: application/json" -d '{"imageRef":"alpine:latest"}'
# 6. When done, stop VS debugger and restart Docker container
docker compose -f docker-compose.dev.yaml start scanner-web
docker compose -f docker-compose.dev.yml start scanner-web
```
### Workflow 2: Debug Multiple Services Together
@@ -340,7 +347,7 @@ docker compose -f docker-compose.dev.yaml start scanner-web
```bash
# 1. Stop both containers
docker compose -f docker-compose.dev.yaml stop scanner-web scanner-worker
docker compose -f docker-compose.dev.yml stop scanner-web scanner-worker
# 2. In Visual Studio, configure multiple startup projects:
# - Right-click solution > Properties
@@ -361,8 +368,8 @@ cd src\Concelier\StellaOps.Concelier.WebService
dotnet build
# 2. Stop Docker Concelier
cd ..\..\..\deploy\compose
docker compose -f docker-compose.dev.yaml stop concelier
cd ..\..\..\devops\compose
docker compose -f docker-compose.dev.yml stop concelier
# 3. Run Concelier in Visual Studio (F5)
@@ -371,7 +378,7 @@ docker compose -f docker-compose.dev.yaml stop concelier
CONCELIER_BASEURL=http://host.docker.internal:5000
# 5. Restart Scanner to pick up new config
docker compose -f docker-compose.dev.yaml restart scanner-web
docker compose -f docker-compose.dev.yml restart scanner-web
```
### Workflow 4: Reset Database State
@@ -380,17 +387,17 @@ docker compose -f docker-compose.dev.yaml restart scanner-web
```bash
# 1. Stop all services
docker compose -f docker-compose.dev.yaml down
docker compose -f docker-compose.dev.yml down
# 2. Remove database volumes
docker volume rm compose_postgres-data
docker volume rm compose_valkey-data
# 3. Restart platform (will recreate volumes and databases)
docker compose -f docker-compose.dev.yaml up -d
docker compose -f docker-compose.dev.yml up -d
# 4. Wait for migrations to run
docker compose -f docker-compose.dev.yaml logs -f postgres
docker compose -f docker-compose.dev.yml logs -f postgres
# Look for migration completion messages
```
@@ -400,7 +407,7 @@ docker compose -f docker-compose.dev.yaml logs -f postgres
```bash
# 1. Use the air-gap compose profile
cd deploy\compose
cd devops\compose
docker compose -f docker-compose.airgap.yaml up -d
# 2. Verify no external network calls
@@ -519,18 +526,18 @@ Note: StackExchange.Redis reports "redis server(s)" even when Valkey is the back
1. **Check Valkey is running:**
```bash
docker compose -f docker-compose.dev.yaml ps valkey
docker compose -f docker-compose.dev.yml ps valkey
# Should show: State = "Up"
# Check logs
docker compose -f docker-compose.dev.yaml logs valkey
docker compose -f docker-compose.dev.yml logs valkey
```
2. **Reset Valkey:**
```bash
docker compose -f docker-compose.dev.yaml stop valkey
docker compose -f docker-compose.dev.yml stop valkey
docker volume rm compose_valkey-data
docker compose -f docker-compose.dev.yaml up -d valkey
docker compose -f docker-compose.dev.yml up -d valkey
```
#### 5. Service Cannot Reach host.docker.internal
@@ -546,7 +553,7 @@ Should work automatically with Docker Desktop.
**Solution (Linux):**
Add to docker-compose.dev.yaml:
Add to docker-compose.dev.yml:
```yaml
services:
scanner-web:
@@ -644,7 +651,7 @@ Permission denied writing to /data/db
sudo chown -R $USER:$USER ./volumes
# Or run Docker as root (not recommended for production)
sudo docker compose -f docker-compose.dev.yaml up -d
sudo docker compose -f docker-compose.dev.yml up -d
```
---
@@ -699,19 +706,19 @@ cd devops\compose
docker compose -f docker-compose.stella-ops.yml up -d
# Stop a specific service for debugging
docker compose -f docker-compose.dev.yaml stop <service-name>
docker compose -f docker-compose.dev.yml stop <service-name>
# View logs
docker compose -f docker-compose.dev.yaml logs -f <service-name>
docker compose -f docker-compose.dev.yml logs -f <service-name>
# Restart a service
docker compose -f docker-compose.dev.yaml restart <service-name>
docker compose -f docker-compose.dev.yml restart <service-name>
# Stop all services
docker compose -f docker-compose.dev.yaml down
docker compose -f docker-compose.dev.yml down
# Stop all services and remove volumes (DESTRUCTIVE)
docker compose -f docker-compose.dev.yaml down -v
docker compose -f docker-compose.dev.yml down -v
# Build the module solution (see docs/dev/SOLUTION_BUILD_GUIDE.md)
cd C:\dev\New folder\git.stella-ops.org