# Installation guide (Docker Compose + air-gap)

This guide explains how to run StellaOps from this repository using deterministic deployment bundles under `deploy/`.

## Prerequisites
- Docker Engine with Compose v2.
- 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.

## Connected host (dev / evaluation)

StellaOps ships reproducible Compose profiles pinned to immutable digests.

```bash
cd deploy/compose
cp env/dev.env.example dev.env
docker compose --env-file dev.env -f docker-compose.dev.yaml config
docker compose --env-file dev.env -f docker-compose.dev.yaml up -d
```

Verify:

```bash
docker compose --env-file dev.env -f docker-compose.dev.yaml ps
```

Defaults are defined by the selected env file. For the dev profile, the UI listens on `https://localhost:8443` by default; see `deploy/compose/env/dev.env.example` for the full port map.

## Air-gapped host (Compose profile)

Use the air-gap profile to avoid outbound hostnames and to align defaults with offline operation:

```bash
cd deploy/compose
cp env/airgap.env.example airgap.env
docker compose --env-file airgap.env -f docker-compose.airgap.yaml config
docker compose --env-file airgap.env -f docker-compose.airgap.yaml up -d
```

For offline bundles, imports, and update workflows, use:
- `docs/24_OFFLINE_KIT.md`
- `docs/airgap/overview.md`
- `docs/airgap/importer.md`
- `docs/airgap/controller.md`

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

## Quota / licensing (optional)

Quota enforcement is configuration-driven. For the current posture and operational implications, see:
- `docs/33_333_QUOTA_OVERVIEW.md`
- `docs/30_QUOTA_ENFORCEMENT_FLOW1.md`
- `docs/license-jwt-quota.md`

## Next steps
- Quick start: `docs/quickstart.md`
- Architecture overview: `docs/40_ARCHITECTURE_OVERVIEW.md`
- Detailed technical index: `docs/technical/README.md`
- Roadmap: `docs/05_ROADMAP.md`