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

Installation Guide

How to run Stella Ops from this repository using Docker Compose.

Prerequisites

• Docker Engine with Compose v2 (docker compose version)
• Enough disk for container images plus scan artifacts (SBOMs, logs, caches)
• For production-style installs, plan for persistent volumes (PostgreSQL + object storage) and a secrets provider

Quick path (automated setup scripts)

The fastest way to get running. The setup scripts validate prerequisites, configure the environment, start infrastructure, build solutions, build Docker images, and launch the full platform.

Windows (PowerShell 7):

.\scripts\setup.ps1              # full setup
.\scripts\setup.ps1 -InfraOnly   # infrastructure only (PostgreSQL, Valkey, RustFS, Rekor, Zot)

Linux / macOS:

./scripts/setup.sh               # full setup
./scripts/setup.sh --infra-only  # infrastructure only

The scripts will:

1. Check prerequisites (dotnet 10.x, node 20+, docker, git)
2. Offer to install hosts file entries automatically
3. Copy env/stellaops.env.example to .env if needed (works out of the box)
4. Start infrastructure and wait for healthy containers
5. Build .NET solutions and Docker images
6. Launch the full platform with health checks

Open https://stella-ops.local when setup completes.

Manual path (step by step)

1. Environment file

cd devops/compose
cp env/stellaops.env.example .env

The example file ships with working local-dev defaults. For production, change POSTGRES_PASSWORD and review all values.

2. Hosts file

Stella Ops services bind to unique loopback IPs so all can use port 443 without collisions. Add the entries from devops/compose/hosts.stellaops.local to your hosts file:

• Windows: C:\Windows\System32\drivers\etc\hosts (run editor as Administrator)
• Linux / macOS: sudo sh -c 'cat devops/compose/hosts.stellaops.local >> /etc/hosts'

3. Start infrastructure

cd devops/compose
docker compose -f docker-compose.dev.yml up -d
docker compose -f docker-compose.dev.yml ps    # verify all healthy

4. Start the full platform

docker compose -f docker-compose.stella-ops.yml up -d

Optional overlays:

# With Sigstore transparency log
docker compose -f docker-compose.stella-ops.yml --profile sigstore up -d

# With telemetry stack (Prometheus, Tempo, Loki)
docker compose -f docker-compose.stella-ops.yml -f docker-compose.telemetry.yml up -d

4a. Migration preflight and execution

Run a migration preflight after bringing up the stack:

# Check migration status for currently registered CLI modules
stella system migrations-status --module all

# Validate checksums for currently registered CLI modules
stella system migrations-verify --module all

# Optional: preview release migrations before any execution
stella system migrations-run --module all --category release --dry-run

If release migrations must be executed:

stella system migrations-run --module all --category release --force
stella system migrations-status --module all

Canonical policy for upgradeable on-prem installs:

• Use this CLI sequence as the required migration gate before rollouts and cutovers.
• Do not rely on Postgres init scripts for release upgrades.
• Use docs/db/MIGRATION_CONSOLIDATION_PLAN.md and docs/db/MIGRATION_INVENTORY.md to confirm module coverage and cutover wave state.
• On empty migration history, CLI/API paths synthesize one per-service consolidated migration (100_consolidated_<service>.sql) and then backfill legacy migration history rows to preserve incremental upgrade compatibility.
• If consolidated history exists with partial legacy backfill, CLI/API paths auto-backfill missing legacy rows before source-set execution.
• UI-driven migration operations must call Platform WebService admin endpoints (/api/v1/admin/migrations/*) with platform.setup.admin; do not connect the browser directly to PostgreSQL.
• Platform migration API implementation is in src/Platform/StellaOps.Platform.WebService/Endpoints/MigrationAdminEndpoints.cs and uses src/Platform/__Libraries/StellaOps.Platform.Database/MigrationModuleRegistry.cs.

Notes:

• Compose PostgreSQL bootstrap scripts in devops/compose/postgres-init run only on first database initialization.
• Startup-hosted migrations are currently wired only for selected modules; CLI coverage is also module-limited.
• For the authoritative current-state module matrix, use docs/db/MIGRATION_INVENTORY.md.

5. Verify

docker compose -f docker-compose.stella-ops.yml ps
curl -k https://stella-ops.local    # should return the Angular UI

Air-gapped deployments

For offline/air-gapped environments, use the sealed CI compose file and offline telemetry overlay:

# Sealed CI environment (authority, signer, attestor in isolation)
docker compose -f docker-compose.sealed-ci.yml up -d

# Offline observability (no external endpoints)
docker compose -f docker-compose.stella-ops.yml -f docker-compose.telemetry-offline.yml up -d

# Tile proxy for air-gapped Sigstore verification
docker compose -f docker-compose.stella-ops.yml -f docker-compose.tile-proxy.yml up -d

For offline bundles, imports, and update workflows, see:

• docs/OFFLINE_KIT.md
• docs/modules/airgap/guides/overview.md

Regional compliance overlays

Region	Testing	Production
China (SM2/SM3/SM4)	docker-compose.compliance-china.yml + docker-compose.crypto-sim.yml	docker-compose.compliance-china.yml + docker-compose.sm-remote.yml
Russia (GOST)	docker-compose.compliance-russia.yml + docker-compose.crypto-sim.yml	docker-compose.compliance-russia.yml + docker-compose.cryptopro.yml
EU (eIDAS)	docker-compose.compliance-eu.yml + docker-compose.crypto-sim.yml	docker-compose.compliance-eu.yml

See devops/compose/README.md for detailed compliance deployment instructions.

Hardening: require Authority for Concelier job triggers

If Concelier is exposed to untrusted networks, require Authority-issued tokens for /jobs* endpoints:

CONCELIER_AUTHORITY__ENABLED=true
CONCELIER_AUTHORITY__ALLOWANONYMOUSFALLBACK=false

Store the client secret outside source control (Docker secrets, mounted file, or Kubernetes Secret). For audit fields and alerting guidance, see docs/modules/concelier/operations/authority-audit-runbook.md.

Next steps

• Quickstart: docs/quickstart.md
• Developer setup details: docs/dev/DEV_ENVIRONMENT_SETUP.md
• Architecture overview: docs/ARCHITECTURE_OVERVIEW.md
• Compose profiles reference: devops/compose/README.md