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)
• Seed the local admin credential from STELLAOPS_ADMIN_PASS (default Admin@Stella2026!)
• 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

Local admin credentials

The local compose template ships with:

• Username: admin
• Password env var: STELLAOPS_ADMIN_PASS
• Default local value: Admin@Stella2026!

Override it before running setup if you do not want the default local password:

$env:STELLAOPS_ADMIN_PASS = 'Admin@Stella2026!'
.\scripts\setup.ps1

export STELLAOPS_ADMIN_PASS='Admin@Stella2026!'
./scripts/setup.sh

Local UI builds that actually reach stella-ops.local

By default the local frontdoor serves the Angular console from the console-dist Docker volume. That means a plain ng build can succeed while the browser still shows the old UI bundle.

For active UI work, switch the gateway to the bind-mounted dev override once:

cd devops/compose
docker compose -f docker-compose.stella-ops.yml -f docker-compose.dev-ui.yml up -d router-gateway
cd ../../src/Web/StellaOps.Web
npx ng build --configuration=development --watch

After that, refresh https://stella-ops.local after rebuilds. The local auth and Playwright helpers already tolerate self-signed local certificates; keep product runtime TLS validation strict.

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. Open https://stella-ops.local.
4. Sign in with admin and the STELLAOPS_ADMIN_PASS value used during setup. Default local password: Admin@Stella2026!.
5. If the install opens the setup wizard, continue the first-run or reconfigure flow from the authenticated session.

Optional demo datasets are manual-only and not part of the default bootstrap path. If you explicitly need them for demo purposes, use the manual seeding section in DEV_ENVIRONMENT_SETUP.md.

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 stella --verbose ... or crypto diagnostics	Optional China SM Remote plugin probe	Non-blocking for default crypto profile; ordinary CLI payload commands now suppress this startup noise
Manual demo seed endpoint still returns HTTP 500 after patching source	Running old container image	Rebuild/restart platform image and retest
ng build succeeds but stella-ops.local still shows the old UI	router-gateway is still serving the console-dist Docker volume	Apply docker-compose.dev-ui.yml with docker compose -f devops/compose/docker-compose.stella-ops.yml -f devops/compose/docker-compose.dev-ui.yml up -d router-gateway, then rebuild the Angular app
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