Installation Guide

Audience: developers and contributors bringing Stella Ops up from a source checkout with Docker Compose.

Which install path do you want?

If you are evaluating or deploying Stella Ops, this is the wrong page.

The supported install path is the release bundle: published images, a single docker-compose.yml, one installer script, no source checkout and no build. Its documentation is devops/release/bundle/README.md, which ships inside the bundle and is the authoritative operator-facing install text.

Building from source is not an offered install path. Stella Ops remains source-available under BUSL-1.1 and everything needed to build it is in this repository — but a source build is a contributor workflow, not a deployment method, and it is not what a customer install looks like. This page documents the contributor workflow.

The release version is v1.0.0-RC1— the same string migration 092_PlatformVersionSetting.sql seeds as the installation-wide PlatformVersion setting and the console sidebar renders.

Release availability — re-measured 2026-09-15: the images ARE published

Superseding the 2026-07-28/29 measurement recorded here, which said they were not. Probed registry.stella-ops.org over the OCI Distribution API on 2026-09-15: the stellaops/ namespace exists, _catalog lists 50 repositories, and every v1.0.0-RC1 product image answers 200 anonymously on its manifest (checked stellaops/authority, stellaops/concelier, stellaops/scanner-web with no credentials). devops/release/bundle/release-manifest.yaml carries a registry digest for all 45 Stella-owned images and names its detached signature; its digest: values match the live sha256-* attestation tags.

So the instructions below work as written, and the earlier caveat no longer applies. Two consequences of the same measurement are tracked rather than hidden: the published images did not carry the licence they are granted under (SPRINT_20260825_016 LRS-17, remediated in the build paths and recorded in docs/legal/busl/image-publications.sha256), and the download this guide’s sibling install page advertises at get.stella-ops.org/v1.0.0-RC1/ still returns 404 (LRS-18) — pull by digest from the registry, not from that URL.

The 2026-07-28 probe output is kept below as the record of what was true then.

Superseded measurement (2026-07-28/29), kept as the record

⚠ Release availability — measured 2026-07-28

The v1.0.0-RC1 images are not in the registry yet. This is the one place that caveat is stated; the bundle instructions themselves are correct and testable, and will work unchanged the moment the images land.

Probed registry.stella-ops.org directly over the OCI Distribution API. The registry is up and anonymous-readable (GET /v2/ → 200 {}, no WWW-Authenticate), so this is a complete view, not an auth-gated partial one:

• GET /v2/_catalog?n=1000 → {"repositories":["oci-attach","stella-cli","stella-ops-api"]}
• No stellaops/ namespace. Every product image path returns HTTP 404 NAME_UNKNOWN — checked stellaops/{advisoryai-web,router-gateway,authority,scanner-web,vexlens-web}.
• No v1.0.0-RC1 tag on any repository. Both v1.0.0-RC1 and 1.0.0-RC1 return 404 on all three repos.
• The three repositories that do exist are prior artefacts: stella-cli (dev, v1.0, v1.1), oci-attach (dev), and stella-ops-api (68 date-stamped tags, newest 2025101219, plus latest). The newest content in the registry predates this release by roughly nine months.

Consistent with that, release-manifest.yaml carries digest: null for all 48 product images (TODO(verify): unresolved — image was not pushed); only the four third-party infrastructure images resolve. Its signature: block is null, so the bundle is unsigned.

A second, independent issue the same probe surfaced: eight bundle files no longer match their recorded checksums, and install.sh fails closed on that (die "N bundle file(s) do not match release-manifest.yaml"), so a run would abort during verification before reaching the pull.

Both clear with one action: ./tools/build-and-publish.sh --version v1.0.0-RC1 --push --sign (with COSIGN_KEY set). It pushes the images, then pipes the resolved digests through tools/write-manifest.py, which rewrites the manifest with real digests and a freshly hashed bundle: block — so the checksum issue clears as a side effect. It then generates docker-compose.pinned.yml and cosign-signs the manifest.

Until then, the from-source path below is the only way to reach a running console. Tracking: devops/release/HANDOFF-FROM-RELEASE-FINISHER.md.

What RC1 ships once it is installed

This page covers getting the stack up. For what the running stack can actually do — per capability, with the src/ wiring point behind each verdict and the operator prerequisites that gate some of them — see RC1_CAPABILITY_MATRIX.md. The caveat box above is carried there as a row rather than restated, so the two cannot drift apart.

The rest of this guide covers the from-source paths — an automated quick path (setup scripts that do everything end to end) and a manual step-by-step path — plus air-gapped installs, regional compliance overlays, and connector credential setup. For first-run workflows after install, continue to the Quickstart; for fully offline installs, see the Offline Kit guide.

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

ARM64 .NET runtime baseline

For ARM64 deployments, Stella Ops .NET service images must use Debian/Ubuntu glibc-based .NET SDK and ASP.NET runtime images. The ARM64 readiness baseline is linux-arm64 on glibc, not Alpine/musl.

Keep Alpine/musl out of .NET service release images unless a separate dependency audit proves every native NuGet asset and configured runtime provider library supports musl ARM64. See devops/compose/README.md for the compose image policy.

Runtime data assets (read before first deploy)

Stella Ops services depend on runtime data assets that are not produced by dotnet publish— ML model weights for semantic search, JDK/Ghidra for binary analysis, certificates, and more. Without them, services start but operate in degraded mode.

# Download and verify all runtime assets
./devops/runtime-assets/acquire.sh --all

# Or just the embedding model (required for semantic search)
./devops/runtime-assets/acquire.sh --models

# Verify existing assets
./devops/runtime-assets/acquire.sh --verify

See devops/runtime-assets/README.md for the complete inventory, Docker volume mount instructions, and air-gap packaging.

Vulnerability mirror seed import/export

Mirror seeds come from one retained Vulnerabilities corpus publication. Use the configured CLI profile and the owner API; no database connection or tenant selector is accepted.

stella mirror seed export --output-directory ./seed
stella mirror seed validate --seed-directory ./seed
stella mirror seed import --seed-directory ./seed

The owner needs a writable Vulnerabilities:MirrorSeed:StagingRoot; the worker publishes the completed import through the existing corpus publisher. See mirror seeds for scopes, limits, chained deltas, explicit replacement and replay behavior. Source acceptance and deployment are separate receipts in the owning sprint.

The dated payloads under devops/mirror/seeds/ are historical v1 archives for the retired Concelier plane. Do not use those archives or the archived bootstrap scripts for a new install.

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

.\tools\scripts\setup.ps1              # full setup
.\tools\scripts\setup.ps1 -InfraOnly   # infrastructure only (PostgreSQL, Valkey, RustFS, Rekor) + the dev-lab zot registry
.\tools\scripts\setup.ps1 -QaIntegrationFixtures # full setup plus Harbor/GitHub App QA fixtures

Registry roles: zot’s listing under -InfraOnly above is historical framing — per ADR-041, zot is demo/development-lab material (a stand-in customer registry), not part of the release installation, and the product registry surface is the Stella Registry. For what every registry-shaped thing in the estate is (and is not), see the registry topology truth doc.

Linux / macOS:

./tools/scripts/setup.sh               # full setup
./tools/scripts/setup.sh --infra-only  # infrastructure only
./tools/scripts/setup.sh --qa-integration-fixtures # full setup plus Harbor/GitHub App QA fixtures

The scripts will:

1. Check prerequisites (dotnet 10.x, node 20+, docker, git)
2. Offer to install hosts file entries automatically
3. Generate an ignored local .env with per-machine secrets if needed
4. Start infrastructure and wait for healthy containers
5. Let Docker Compose create or reuse the platform bridge networks (stellaops and FRONTDOOR_NETWORK, default stellaops_frontdoor)
6. Stop repo-local host-run Stella services that would lock build outputs, then build repo-owned .NET solutions and publish backend services locally into small Docker contexts before building hardened runtime images (vendored or generated trees such as node_modules, dist, coverage, and output are excluded)
7. Launch the full platform with health checks, perform one bounded restart pass for services that stay unhealthy after first boot, wait for the first-user frontdoor bootstrap path (/signin, /envsettings.json, OIDC discovery, /connect/authorize), then complete an authenticated convergence gate that proves topology inventory, notifications administration overrides, and promotion bootstrap flows load cleanly before reporting success
8. If -QaIntegrationFixtures / --qa-integration-fixtures is enabled, start deterministic Harbor and GitHub App fixtures and verify them so the local Integrations Hub can be exercised with successful UI onboarding

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

The automated setup path does not start the real third-party integration compose lane. devops/compose/docker-compose.testing.yml is the CI/testing lane, and the optional real providers live in devops/compose/docker-compose.integrations.yml. GitLab and Consul are opt-in there because they add noticeable idle CPU overhead.

Setup failures after prerequisites, migrations, first-user bootstrap, OIDC discovery, or authenticated readiness are product or documentation defects. Fix the failing script, code path, migration, or documentation and rerun setup. Do not bypass failed gates with seeded tokens, direct SQL edits, skipped checks, or unrelated volume wipes unless this guide explicitly calls for a clean-volume test.

For local compose/source-checkout installs where the existing admin password is stale or unknown, reset it through the compose Authority recovery helper:

$env:STELLAOPS_ADMIN_PASS = '<new-private-password>'
$env:STELLAOPS_ADMIN_PASS |
  .\devops\compose\scripts\authority-password-set.ps1 -Username admin -Tenant default -PasswordStdin

Then update the ignored local env value used by the stack and refresh browser or CLI sessions. This is existing-admin recovery; it is separate from setup-session reset and from fresh first-user bootstrap.

For targeted backend rebuilds after a scoped code change on Windows:

.\devops\docker\build-all.ps1 -Services notify-web,orchestrator

This path avoids re-sending the full monorepo to Docker for every .NET service image.

Manual path (step by step)

1. Environment file

cd devops/compose
./scripts/init-local-env.sh

The script uses env/stellaops.env.local-dev.example and writes an ignored .env file with generated secrets. For production or release installs, start from env/stellaops.env.example, replace every CHANGE_ME value, and source real secrets from the approved secret store.

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:

Runtime URL convention remains *.stella-ops.local; hosts.stellaops.local is the template file name only.

The same template also carries the optional harbor-fixture.stella-ops.local and github-app-fixture.stella-ops.local aliases used by the fixture-backed integrations QA lane.

• 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

The full platform Compose file owns the stellaops and frontdoor bridge networks on local installs. Do not pre-create FRONTDOOR_NETWORK; doing so without Compose labels can make docker compose up fail on a fresh setup.

docker compose --env-file .env -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 convergence and verification

Migrations converge automatically. Every service applies its own embedded Startup-band SQL (001–099) to its own database at host start (AddStartupMigrations); one service = one database + own role. There is no migration preflight command and no manual applier.

After bringing up the stack, verify convergence per service:

# Each service reports its own migration state (db.migration-status) through its doctor endpoint
curl -s https://<gateway>/doctor/<service>/checks

# Or read the owning schema's ledger directly (replace <db> and <schema>)
docker compose exec postgres psql -U stellaops -d <db> \
  -c "select migration_name, category, applied_at from <schema>.schema_migrations order by applied_at desc limit 10;"

Canonical policy for upgradeable on-prem installs:

• Deploy the new service image and restart the service; the owning host converges its schema before it serves traffic. A host that cannot converge fails closed and its container log names the migration and the cause.
• Do not rely on Postgres init scripts for release upgrades. devops/compose/postgres-init/00-v1-baseline.sql runs on first initialization only and creates nothing any service owns (it creates stellaops_authority and Authority’s own authority/authority_app shells plus the guarded default-tenant seed).
• Release-category (100+ or rollback in the name) and Data-category (DM-prefixed) migrations must not exist; the tree is guarded by NoManualCategoryMigrationsTests. If a service reports one pending, renumber it into the Startup band so the owning host applies it, or apply it by hand per docs/runbooks/database/migration-recovery.md and record the ledger row.
• Never connect the browser or any tool directly to PostgreSQL to migrate.
• Retired (SPRINT_20260722_021 PLT-4, 2026-09-14): the stella system migrations-status | migrations-verify | migrations-run preflight sequence this section used to prescribe was deleted with the central migration-plugin mechanism (MigrationModuleRegistry). The central migration admin API had already been retired by SPRINT_20260722_026 (2026-08-02).

Notes:

• Compose PostgreSQL bootstrap scripts in devops/compose/postgres-init run only on first database initialization.
• The collapsed baseline devops/compose/postgres-init/00-v1-baseline.sql (section sourced from the archived 14-platform-environment-settings.sql) now leaves platform.environment_settings empty on fresh local databases so the setup wizard owns first-run completion truth. Older local volumes with the legacy (tenant_id, key) table shape are converged by Platform release migration 064_EnvironmentSettingsInstallationScopeConvergence.sql.
• For the authoritative current-state module matrix, use docs/db/MIGRATION_INVENTORY.md.

4b. PostgreSQL roles the install path must create

This is the one place the requirement is stated. The database-ownership matrix (docs/architecture/database-ownership-matrix.md, section 5.5) points here; nothing restates it.

A schema migration runs as the service’s own role, and that role is provisioned NOSUPERUSER NOCREATEDB NOCREATEROLE — that least privilege is precisely what the ownership boundary is made of (ADR-039; tools/scripts/deploy/postgres/provision-service-database.sh step 1). A migration therefore cannot create a role, and must never try. Role provisioning belongs to the install path, which runs as the PostgreSQL superuser.

Six pre-1.0 baselines still carry a guarded IF NOT EXISTS … CREATE ROLE <service>_admin WITH NOLOGIN BYPASSRLS block. Those files are applied on every existing estate and are immutable (forward-only, ADR-004), so the block cannot be removed — only made unreachable by ensuring the role already exists. It is inert wherever it does, which is every estate to date. On a from-scratch install whose service role is already least-privileged it is a hard boot failure: PostgreSQL answers 42501 permission denied to create role and the service host exits.

What the install path does about it:

• devops/compose/postgres-init/05-service-admin-roles.sql creates the roles it covers as the superuser on first cluster start, before any service connects. The release bundle ships the same file at config/postgres-init/05-service-admin-roles.sql and mounts it into its own PostgreSQL, so a bundle install needs no operator step. As of 2026-09-14 it covers authority_adminand scheduler_admin. The preceding 00-v1-baseline.sql still creates findings_ledger_admin; notify_admin, policy_admin and vex_admin still rely on their own baselines running under a privileged role.

• On a cluster that already exists, or when Stella Ops points at an operator-managed PostgreSQL, run the equivalent once as the superuser before starting the service:

  CREATE ROLE authority_admin WITH NOLOGIN BYPASSRLS;
  

• Authority verifies the role at startup and refuses to migrate without it, naming the role and this section. Do not answer that failure by granting CREATEROLE to the service role: it would clear the error and dissolve the ownership boundary in the same statement.

Verified against implementation commit 2a0788bce4 (AUTH-26). Re-verify both shipped installers, their idempotence, and missing-role refusal with pwsh tools/scripts/test-targeted-xunit.ps1 -Project src/Authority/__Tests/StellaOps.Authority.Persistence.Tests/StellaOps.Authority.Persistence.Tests.csproj -Class '*AuthorityAdminRoleColdStartTests' -BuildProjectReferences.

5. Verify

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

After the Angular UI is reachable, the supported local operator lanes are:

Browser-driven operator lane

Use the live browser UI at https://stella-ops.local and open the Integrations Hub at /setup/integrations.

For a repeatable browser-driven run against the live frontdoor:

node src/Web/StellaOps.Web/scripts/live-integrations-ui-bootstrap.mjs

This harness signs in through the same frontdoor flow, drives the /setup/integrations/onboarding/* routes in a real browser, and writes evidence to src/Web/StellaOps.Web/output/playwright/live-integrations-ui-bootstrap.json.

For a repeatable browser-driven proof of the setup wizard’s truthful state model:

node src/Web/StellaOps.Web/scripts/live-setup-wizard-state-truth-check.mjs

This harness signs in through the frontdoor, forces a fresh installation-scoped setup session, proves that database probe does not complete the step, proves that apply advances the backend state to the cache step, and proves that a page reload resumes the same persisted session. Evidence is written to src/Web/StellaOps.Web/output/playwright/live-setup-wizard-state-truth-check.json.

For a fresh-volume first-run bootstrap proof that drives the full installation wizard, creates the first administrator account, and then proves that the new credentials can authenticate through the frontdoor:

npm --prefix src/Web/StellaOps.Web run test:e2e:platform:bootstrap:first-run:live

Evidence is written to src/Web/StellaOps.Web/output/playwright/live-setup-wizard-first-run-bootstrap.json plus the paired authentication report/state files in the same directory.

Verified current UI boundary on 2026-04-14:

• The browser flow can create the full 16-entry local integration catalog.
• GitLab-class providers can now be created from the UI without a manual Vault write because the Integrations Hub stages credentials through Secret Authority before binding the returned authref://....
• The setup wizard now persists authoritative installation-scoped progress in platform.setup_sessions and owns only the five control-plane steps the running control plane can truthfully converge: PostgreSQL, Valkey, schema migrations, admin bootstrap, and crypto profile.
• The Admin step depends on Platform reaching Authority’s internal bootstrap endpoint with the shared bootstrap API key. In local compose, this is wired by forwarding AUTHORITY_BOOTSTRAP_APIKEY into Platform as STELLAOPS_BOOTSTRAP_KEY.
• For dev/CI bypass paths (runtime default admin bootstrap, env-gated demo seed migration, driver-script setup), see docs/modules/authority/operations/bootstrap-modes.md. Production deployments must use the setup wizard described above. Demo seed mode is sample-data opt-in and is not appropriate for prod.
• Tenant-scoped onboarding stays on /setup/* and other authenticated module surfaces instead of being duplicated inside the bootstrap wizard.
• The CLI now owns the repeatable local GitLab path, including PAT minting and Vault staging, through stella config integrations bootstrap local.
• The Playwright harness still accepts STELLAOPS_UI_BOOTSTRAP_GITLAB_ACCESS_TOKEN and STELLAOPS_UI_BOOTSTRAP_GITLAB_REGISTRY_BASIC when you want the browser flow to use explicit operator-provided values instead of the CLI-owned local bootstrap lane.

CLI convergence lane

For a fresh local developer install, populate the live integration catalog with:

stella auth login
stella config integrations bootstrap local

This converges the default local-ready lane to 13 healthy providers: Harbor fixture, Docker Registry, Nexus, GitHub App fixture, Gitea, Jenkins, Vault, Consul, eBPF runtime-host fixture, MinIO, and the three feed mirror providers (StellaOpsMirror, NvdMirror, OsvMirror).

GitLab server/CI and the GitLab registry remain opt-in but stay inside the same first-party CLI workflow:

stella config integrations bootstrap local --include-gitlab
stella config integrations bootstrap local --include-gitlab --include-gitlab-registry

The CLI mints the owned local stella-local-integration PAT against the compose fixture, stages both authref://vault/gitlab#access-token and authref://vault/gitlab#registry-basic into the writable Vault target, and then verifies the resulting integrations. Start the heavy GitLab profile with GITLAB_ENABLE_REGISTRY=true before using --include-gitlab-registry. The older PowerShell scripts remain available for compatibility and debugging, but they are no longer the preferred product path for the Stella-owned local fixture lane.

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

Each row layers onto docker-compose.stella-ops.yml, and the consolidated Evidence and AdvisoryAI families must come first: they are OPT-IN overlays outside the include chain, and every regional overlay carries fragments for their service keys.

docker compose \
  -f devops/compose/docker-compose.stella-ops.yml \
  -f devops/compose/docker-compose.evidence.yml \
  -f devops/compose/docker-compose.advisoryai.yml \
  -f devops/compose/docker-compose.compliance-eu.yml up -d

ARM64 note: Stella Ops first-party .NET service images are ARM64-ready on Debian/Ubuntu glibc linux-arm64. Local Russian vendor GOST providers are not supported on ARM64 installations in this release unless the operator obtains a provider-supported Debian/Ubuntu linux-arm64 package and route evidence. If you require that path, contact your GOST provider for ARM64 Linux support. Where certification rules allow substitution, use an open-source OpenSSL GOST or PKCS#11 route.

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

Operator-managed trust anchors (CA certificates)

Some upstream advisory feeds (Apple’s gdmf.apple.com, regional CERTs, internal stella-mirror replicas) chain to roots that ship neither in the Ubuntu ca-certificates package nor in your corporate trust bundle. Drop PEM-encoded CAs into etc/trust-anchors/ and Concelier (plus any other service that goes through Connector.Common’s AddSourceHttpClient) will pick them up at startup — no per-connector embed, no rebuilt image.

• Mount path inside containers: /etc/stellaops/trust-anchors (override via env var STELLAOPS_TRUST_ANCHORS_PATH).
• See docs/modules/concelier/operations/trust-anchors.mdfor file format, startup logging, and dev-mode fallback semantics.
• The mount is wired into concelier, excititor-web, excititor-worker, and advisoryai-web in devops/compose/docker-compose.advisoryai.yml. Add the same volumes: + STELLAOPS_TRUST_ANCHORS_PATH env to any other service that needs to trust a private CA.

Connector credentials (vendor advisory feeds)

Concelier ingests vulnerability advisories from many sources. The four auth-gated ones — cisco, microsoft (MSRC), ghsa, cve (CVE.org) — require operator-supplied credentials. Without credentials those connectors log a single WARN on the first cron tick and then no-op silently; they do not fail health checks or accumulate error_count. Wire them when ready.

How to obtain a PAT / OAuth client / API key for each, the exact environment variables to set, and a copy/paste verification command:

• docs/modules/concelier/connectors/credentials-acquisition.md

Companion references:

• credentials-matrix.md— full per-source mechanism inventory (PAT / OAuth / API key / public).
• The stella-mirror connector is disabled by default as of Sprint 20260505_044. It is a downstream relay for air-gap operators who pull a pre-aggregated bundle from a parent Stella Ops deployment; it is not a feed Stella Ops itself consumes from upstream. Activate by setting STELLA_MIRROR_BASE_URL to the parent’s mirror root and flipping enabled=true in vuln.sources (or via the UI).

Vulnerability owner authorization

The hub enforces Authority scopes on its owner routes. Mirror export requires advisory/VEX read scopes; mirror import requires both advisory/VEX ingest scopes. Source status is read through stella config sources list or stella config sources status; source enablement is owner configuration. The retired Concelier job-trigger API is not part of the installation.

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