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

336
docs/dev/DEV_ENVIRONMENT_SETUP.md Normal file
View File

@@ -0,0 +1,336 @@
# Dev Environment Setup
Actionable checklist for getting a local Stella Ops development environment running.
For hybrid debugging workflows and service-specific guides, see [`docs/DEVELOPER_ONBOARDING.md`](../DEVELOPER_ONBOARDING.md).
---
## Quick Start (automated)
Setup scripts validate prerequisites, start infrastructure, build solutions and Docker images, and launch the full platform.
**Windows (PowerShell 7):**
```powershell
.\scripts\setup.ps1 # full setup
.\scripts\setup.ps1 -InfraOnly # infrastructure only (PostgreSQL, Valkey, SeaweedFS, Rekor, Zot)
.\scripts\setup.ps1 -SkipBuild # skip .NET builds, build images and start platform
.\scripts\setup.ps1 -SkipImages # build .NET but skip Docker images
.\scripts\setup.ps1 -ImagesOnly # only build Docker images
```
**Linux / macOS:**
```bash
./scripts/setup.sh # full setup
./scripts/setup.sh --infra-only # infrastructure only
./scripts/setup.sh --skip-build # skip .NET builds
./scripts/setup.sh --skip-images # skip Docker image builds
./scripts/setup.sh --images-only # only build Docker images
```
The scripts will check for required tools (dotnet 10.x, node 20+, npm 10+, docker, git), warn about missing hosts file entries, and copy `.env` from the example if needed. See the manual steps below for details on each stage.
---
## 1. Prerequisites
| Tool | Version | Verify |
|------|---------|--------|
| .NET 10 SDK | 10.0.100 (pinned in `global.json`) | `dotnet --version` |
| Node.js | ^20.19.0 \|\| ^22.12.0 \|\| ^24.0.0 | `node --version` |
| npm | >=10.2.0 | `npm --version` |
| Docker Desktop / Engine + Compose | 20.10+ | `docker --version` |
| Git | 2.30+ | `git --version` |
| PowerShell 7+ (Windows) or Bash | -- | `pwsh --version` / `bash --version` |
### Optional
- Visual Studio 2022 v17.12+ (ASP.NET and web development workload)
- VS Code + C# Dev Kit
- PostgreSQL client (`psql`, DBeaver, pgAdmin)
- `valkey-cli` or Redis Insight (Valkey is Redis-compatible)
- AWS CLI or `s3cmd` for RustFS inspection
### System requirements
- **RAM:** 16 GB minimum, 32 GB recommended
- **Disk:** 50 GB free (Docker images, volumes, build artifacts)
- **CPU:** 4 cores minimum, 8 cores recommended
---
## 2. Hosts file setup
Each service binds to a unique loopback IP so all can use ports 443/80 without collisions.
Full details: [`docs/technical/architecture/port-registry.md`](../technical/architecture/port-registry.md).
Add the block below to your hosts file:
- **Windows:** `C:\Windows\System32\drivers\etc\hosts` (run editor as Administrator)
- **Linux / macOS:** `/etc/hosts` (use `sudo`)
```
# Stella Ops local development hostnames
# Each service gets a unique loopback IP so all can bind :443/:80 simultaneously.
127.1.0.1 stella-ops.local
127.1.0.2 router.stella-ops.local
127.1.0.3 platform.stella-ops.local
127.1.0.4 authority.stella-ops.local
127.1.0.5 gateway.stella-ops.local
127.1.0.6 attestor.stella-ops.local
127.1.0.7 evidencelocker.stella-ops.local
127.1.0.8 scanner.stella-ops.local
127.1.0.9 concelier.stella-ops.local
127.1.0.10 excititor.stella-ops.local
127.1.0.11 vexhub.stella-ops.local
127.1.0.12 vexlens.stella-ops.local
127.1.0.13 vulnexplorer.stella-ops.local
127.1.0.14 policy-engine.stella-ops.local
127.1.0.15 policy-gateway.stella-ops.local
127.1.0.16 riskengine.stella-ops.local
127.1.0.17 orchestrator.stella-ops.local
127.1.0.18 taskrunner.stella-ops.local
127.1.0.19 scheduler.stella-ops.local
127.1.0.20 graph.stella-ops.local
127.1.0.21 cartographer.stella-ops.local
127.1.0.22 reachgraph.stella-ops.local
127.1.0.23 timelineindexer.stella-ops.local
127.1.0.24 timeline.stella-ops.local
127.1.0.25 findings.stella-ops.local
127.1.0.26 doctor.stella-ops.local
127.1.0.27 opsmemory.stella-ops.local
127.1.0.28 notifier.stella-ops.local
127.1.0.29 notify.stella-ops.local
127.1.0.30 signer.stella-ops.local
127.1.0.31 smremote.stella-ops.local
127.1.0.32 airgap-controller.stella-ops.local
127.1.0.33 airgap-time.stella-ops.local
127.1.0.34 packsregistry.stella-ops.local
127.1.0.35 registry-token.stella-ops.local
127.1.0.36 binaryindex.stella-ops.local
127.1.0.37 issuerdirectory.stella-ops.local
127.1.0.38 symbols.stella-ops.local
127.1.0.39 sbomservice.stella-ops.local
127.1.0.40 exportcenter.stella-ops.local
127.1.0.41 replay.stella-ops.local
127.1.0.42 integrations.stella-ops.local
127.1.0.43 signals.stella-ops.local
127.1.0.44 advisoryai.stella-ops.local
127.1.0.45 unknowns.stella-ops.local
# Stella Ops infrastructure (local dev containers)
127.1.1.1 db.stella-ops.local
127.1.1.2 cache.stella-ops.local
127.1.1.3 s3.stella-ops.local
127.1.1.4 rekor.stella-ops.local
127.1.1.5 registry.stella-ops.local
```
---
## 3. Start infrastructure (Docker)
```bash
cd devops/compose
cp env/stellaops.env.example .env # edit POSTGRES_PASSWORD at minimum
docker compose -f docker-compose.dev.yml up -d
docker compose -f docker-compose.dev.yml ps
```
### Verify infrastructure
```bash
# PostgreSQL
psql -h db.stella-ops.local -U stellaops -d stellaops_dev -c "SELECT 1"
# Valkey
valkey-cli -h cache.stella-ops.local ping
```
Infrastructure versions (from `docker-compose.dev.yml`):
| Service | Version | Hostname | Port |
|---------|---------|----------|------|
| PostgreSQL | 18.1 | `db.stella-ops.local` | 5432 |
| Valkey | 9.0.1 | `cache.stella-ops.local` | 6379 |
| SeaweedFS (S3) | -- | `s3.stella-ops.local` | 8080 |
| Rekor v2 | -- | `rekor.stella-ops.local` | 3322 |
| Zot (OCI registry) | v2.1.3 | `registry.stella-ops.local` | 80 |
---
## 4. Build .NET modules
The codebase uses a **module-first** approach -- there is no root solution file used for builds. Each module has its own `.sln` under `src/<Module>/`.
### Single module
```powershell
dotnet build src\Scanner\StellaOps.Scanner.sln
dotnet test src\Scanner\StellaOps.Scanner.sln
```
### All modules
```powershell
# Windows (PowerShell 7)
.\scripts\build-all-solutions.ps1
# With tests
.\scripts\build-all-solutions.ps1 -Test
# Linux / macOS
./scripts/build-all-solutions.sh
# With tests
./scripts/build-all-solutions.sh --test
```
### Module solution index
See [`docs/dev/SOLUTION_BUILD_GUIDE.md`](SOLUTION_BUILD_GUIDE.md) for the authoritative list. Current modules (39):
| Module | Solution path |
|--------|---------------|
| AdvisoryAI | `src/AdvisoryAI/StellaOps.AdvisoryAI.sln` |
| AirGap | `src/AirGap/StellaOps.AirGap.sln` |
| Aoc | `src/Aoc/StellaOps.Aoc.sln` |
| Attestor | `src/Attestor/StellaOps.Attestor.sln` |
| Authority | `src/Authority/StellaOps.Authority.sln` |
| Bench | `src/Bench/StellaOps.Bench.sln` |
| BinaryIndex | `src/BinaryIndex/StellaOps.BinaryIndex.sln` |
| Cartographer | `src/Cartographer/StellaOps.Cartographer.sln` |
| Cli | `src/Cli/StellaOps.Cli.sln` |
| Concelier | `src/Concelier/StellaOps.Concelier.sln` |
| EvidenceLocker | `src/EvidenceLocker/StellaOps.EvidenceLocker.sln` |
| Excititor | `src/Excititor/StellaOps.Excititor.sln` |
| ExportCenter | `src/ExportCenter/StellaOps.ExportCenter.sln` |
| Feedser | `src/Feedser/StellaOps.Feedser.sln` |
| Findings | `src/Findings/StellaOps.Findings.sln` |
| Gateway | `src/Gateway/StellaOps.Gateway.sln` |
| Graph | `src/Graph/StellaOps.Graph.sln` |
| IssuerDirectory | `src/IssuerDirectory/StellaOps.IssuerDirectory.sln` |
| Notifier | `src/Notifier/StellaOps.Notifier.sln` |
| Notify | `src/Notify/StellaOps.Notify.sln` |
| Orchestrator | `src/Orchestrator/StellaOps.Orchestrator.sln` |
| PacksRegistry | `src/PacksRegistry/StellaOps.PacksRegistry.sln` |
| Policy | `src/Policy/StellaOps.Policy.sln` |
| ReachGraph | `src/ReachGraph/StellaOps.ReachGraph.sln` |
| Registry | `src/Registry/StellaOps.Registry.sln` |
| Replay | `src/Replay/StellaOps.Replay.sln` |
| RiskEngine | `src/RiskEngine/StellaOps.RiskEngine.sln` |
| Router | `src/Router/StellaOps.Router.sln` |
| SbomService | `src/SbomService/StellaOps.SbomService.sln` |
| Scanner | `src/Scanner/StellaOps.Scanner.sln` |
| Scheduler | `src/Scheduler/StellaOps.Scheduler.sln` |
| Signer | `src/Signer/StellaOps.Signer.sln` |
| Signals | `src/Signals/StellaOps.Signals.sln` |
| SmRemote | `src/SmRemote/StellaOps.SmRemote.sln` |
| TaskRunner | `src/TaskRunner/StellaOps.TaskRunner.sln` |
| Telemetry | `src/Telemetry/StellaOps.Telemetry.sln` |
| TimelineIndexer | `src/TimelineIndexer/StellaOps.TimelineIndexer.sln` |
| Tools | `src/Tools/StellaOps.Tools.sln` |
| VexHub | `src/VexHub/StellaOps.VexHub.sln` |
| VexLens | `src/VexLens/StellaOps.VexLens.sln` |
| VulnExplorer | `src/VulnExplorer/StellaOps.VulnExplorer.sln` |
| Zastava | `src/Zastava/StellaOps.Zastava.sln` |
---
## 5. Build Angular frontend
```bash
cd src/Web/StellaOps.Web
npm ci --prefer-offline --no-audit --no-fund
npm run start # dev server -> https://stella-ops.local
npm run build # production build
npm run test # unit tests (Vitest)
npm run test:e2e # Playwright E2E
```
Additional scripts:
| Command | Purpose |
|---------|---------|
| `npm run storybook` | Launch Storybook component explorer |
| `npm run analyze` | Bundle size visualization (esbuild-visualizer) |
| `npm run test:a11y` | Accessibility smoke tests |
---
## 6. Build Docker images
### Option A: Build all services (matrix-driven)
```bash
cd devops/docker
./build-all.sh
```
Uses `services-matrix.env` and `Dockerfile.hardened.template` for .NET services, `Dockerfile.console` for Angular.
### Option B: Build a single .NET service
```bash
docker build -f devops/docker/Dockerfile.hardened.template . \
--build-arg SDK_IMAGE=mcr.microsoft.com/dotnet/sdk:10.0-bookworm-slim \
--build-arg RUNTIME_IMAGE=mcr.microsoft.com/dotnet/aspnet:10.0-bookworm-slim \
--build-arg APP_PROJECT=src/Scanner/StellaOps.Scanner.WebService/StellaOps.Scanner.WebService.csproj \
--build-arg APP_BINARY=StellaOps.Scanner.WebService \
--build-arg APP_PORT=8080 \
-t stellaops/scanner-web:dev
```
### Option C: Build the Angular console image
```bash
docker build -f devops/docker/Dockerfile.console . \
--build-arg APP_DIR=src/Web/StellaOps.Web \
-t stellaops/console:dev
```
### Release-quality builds (distroless)
Release Dockerfiles live under `devops/release/docker/`:
- `Dockerfile.dotnet-service` -- .NET services
- `Dockerfile.angular-ui` -- Angular console
Component manifest: `devops/release/components.json`.
---
## 7. Run the full platform
```bash
# Core services
docker compose -f devops/compose/docker-compose.stella-ops.yml up -d
# With Sigstore transparency log
docker compose -f devops/compose/docker-compose.stella-ops.yml --profile sigstore up -d
# With telemetry stack
docker compose -f devops/compose/docker-compose.stella-ops.yml \
-f devops/compose/docker-compose.telemetry.yml up -d
```
Verify:
```bash
docker compose -f devops/compose/docker-compose.stella-ops.yml ps
```
---
## 8. Hybrid debugging (quick reference)
1. Start the full platform in Docker (section 7).
2. Stop the container for the service you want to debug:
```bash
docker compose -f devops/compose/docker-compose.stella-ops.yml stop <service-name>
```
3. Run that service locally from your IDE (F5 in Visual Studio, or `dotnet run`).
4. The local service uses `localhost` / `.stella-ops.local` hostnames to reach Docker-hosted infrastructure.
For detailed walkthroughs, configuration overrides, and multi-service debugging see [`docs/DEVELOPER_ONBOARDING.md`](../DEVELOPER_ONBOARDING.md).