git.stella-ops.org/docs/quickstart.md

Quickstart -- Local Dev Environment in Minutes

Get Stella Ops running locally for development and evaluation.

This guide is for local development. For production deployment, see the Installation Guide.

Prerequisites

Requirement	Minimum	Verify
OS	Windows 10+, macOS 12+, Ubuntu 22.04+	x86-64 or arm64
Docker	Engine 20.10+ with Compose v2	docker compose version
.NET SDK	10.x	dotnet --version
Node.js	20+	node --version
RAM	16 GB (32 GB recommended)
Disk	50 GB free

0. Runtime data assets (optional but recommended)

Some services depend on files not produced by dotnet build — most notably the ONNX embedding model for semantic search. Without it, search works but with reduced quality.

# After cloning, download the embedding model (~80 MB)
./devops/runtime-assets/acquire.sh --models

# Verify everything is in place
./devops/runtime-assets/acquire.sh --verify

For binary analysis (Ghidra), add --ghidra (~1.6 GB). Full details: devops/runtime-assets/README.md.

---

1. Clone the repository

git clone <your-gitea-instance>/stella-ops/stella-ops.git
cd stella-ops

2. Run setup

Windows (PowerShell 7):

.\scripts\setup.ps1

Linux / macOS:

./scripts/setup.sh

The setup script will:

• Verify all prerequisites are installed
• Offer to add hosts file entries (50 services need unique loopback IPs)
• Create .env from the example template (works out of the box, no editing needed)
• Create or reuse the external frontdoor Docker network from .env (FRONTDOOR_NETWORK, default stellaops_frontdoor)
• Build .NET solutions and Docker images
• Launch the full platform stack (docker-compose.stella-ops.yml)
• Run health checks and report status

Infrastructure only (faster)

To skip builds and only start infrastructure:

.\scripts\setup.ps1 -InfraOnly     # Windows
./scripts/setup.sh --infra-only    # Linux/macOS

3. First 30 minutes path

1. Start platform quickly (reuse existing images):

   .\scripts\setup.ps1 -SkipBuild -SkipImages
   

2. Confirm service health:

   docker compose -f devops/compose/docker-compose.stella-ops.yml ps
   

3. Preview demo seeding:

   dotnet run --project src/Cli/StellaOps.Cli/StellaOps.Cli.csproj -- `
     admin seed-demo --dry-run `
     --connection "Host=127.1.1.1;Port=5432;Database=stellaops_platform;Username=stellaops;Password=stellaops"
   

4. Seed demo data:

   dotnet run --project src/Cli/StellaOps.Cli/StellaOps.Cli.csproj -- `
     admin seed-demo --confirm `
     --connection "Host=127.1.1.1;Port=5432;Database=stellaops_platform;Username=stellaops;Password=stellaops"
   

5. Open https://stella-ops.local.

What's running

After a full setup, you'll have 60+ services running locally:

Service	URL	Purpose
Web UI	https://stella-ops.local	Angular console
Authority	https://authority.stella-ops.local	OAuth2/OIDC
Scanner	https://scanner.stella-ops.local	SBOM/vulnerability scanning
Concelier	https://concelier.stella-ops.local	Advisory aggregation
PostgreSQL	db.stella-ops.local:5432	Primary database
Valkey	cache.stella-ops.local:6379	Cache and messaging
RustFS	s3.stella-ops.local:8333	S3-compatible object storage

Full service list: devops/compose/docker-compose.stella-ops.yml

Runtime URL convention: use *.stella-ops.local hostnames for services. Exception: hosts.stellaops.local is a file name, not a runtime host.

Optional Sigstore services (rekor-v2, rekor-cli, cosign) are enabled only with:

docker compose -f devops/compose/docker-compose.stella-ops.yml --profile sigstore up -d

Troubleshooting

Symptom	Meaning	Action
stella-ops.local not found	Hosts entries missing	Re-run setup and accept hosts installation, or append devops/compose/hosts.stellaops.local manually
health=starting for RustFS during setup	Advisory startup lag	Wait 30-60 seconds and re-check docker compose ... ps
stellaops-dev-rekor restarting without --profile sigstore	Optional profile container from older runs	Non-blocking for default setup; ignore or clean old container
SM remote service probe failed (localhost:56080) in CLI	Optional China SM Remote plugin probe	Non-blocking for default crypto profile
admin seed-demo --confirm fails with scheduler_exceptions_tenant_isolation already exists	Outdated Scheduler migration scripts	Pull latest code and rerun seeding
Seed endpoint still returns HTTP 500 after patching source	Running old container image	Rebuild/restart platform image and retest
Port conflicts	Local process already using mapped port	Override in devops/compose/.env (devops/compose/env/stellaops.env.example)

Next steps

• Developer setup details -- manual steps, hybrid debugging, building individual modules
• Installation Guide -- production deployment, air-gap, regional compliance
• Architecture overview -- how the platform fits together