# 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//`. ### 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 ``` 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).