stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
5548cf83bf8114fd7921f35fde4c2ff3dea863bf
git.stella-ops.org/docs/dev/DEV_ENVIRONMENT_SETUP.md
master 5548cf83bf part #2
2026-02-04 19:59:20 +02:00

11 KiB
Raw Blame History

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.

Quick Start (automated)

Setup scripts validate prerequisites, start infrastructure, build solutions and Docker images, and launch the full platform.

Windows (PowerShell 7):

.\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:

./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.

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)

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

# 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

dotnet build src\Scanner\StellaOps.Scanner.sln
dotnet test  src\Scanner\StellaOps.Scanner.sln

All modules

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

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)

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

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

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

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

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: 
    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.