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

## 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.

```bash
# 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.

---

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

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

**Linux / macOS:**

```bash
./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. Create or reuse the external frontdoor Docker network from `.env` (`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 (`/welcome`, `/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

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

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

```powershell
.\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

```bash
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:

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

- **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

```bash
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

Create or reuse the external frontdoor network first:

```bash
docker network inspect "${FRONTDOOR_NETWORK:-stellaops_frontdoor}" >/dev/null 2>&1 || \
  docker network create "${FRONTDOOR_NETWORK:-stellaops_frontdoor}"
```

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

Optional overlays:

```bash
# 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:

```bash
# 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:

```bash
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

```bash
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:

```bash
# 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:

```bash
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`