# Stella Ops — Installation Guide (Docker & Air‑Gap)

<!--
  This file is processed by the Eleventy build.  
  Do **not** hard‑code versions or quota numbers; inherit from
  docs/_includes/CONSTANTS.md instead.
    {{ dotnet }}     → ".NET 10 LTS"
    {{ angular }}    → "20"
-->

> **Status — public α not yet published.**  
> The commands below will work as soon as the first image is tagged  
> `registry.stella-ops.org/stella-ops/stella-ops:0.1.0-alpha`  
> (target date: **late 2025**). Track progress on the  
> [road‑map](/roadmap/).

---

## 0 · Prerequisites

| Item | Minimum | Notes |
|------|---------|-------|
| Linux | Ubuntu 22.04 LTS / Alma 9 | x86‑64 or arm64 |
| CPU / RAM | 2 vCPU / 2 GiB | Laptop baseline |
| Disk | 10 GiB SSD | SBOM + vuln DB cache |
| Docker | **Engine 25 + Compose v2** | `docker -v` |
| TLS | OpenSSL 1.1 +  | Self‑signed cert generated at first run |

---

## 1 · Connected‑host install (Docker Compose)

```bash
# 1. Make a working directory
mkdir stella && cd stella

# 2. Download the signed Compose bundle + example .env
curl -LO https://get.stella-ops.org/releases/latest/.env.example
curl -LO https://get.stella-ops.org/releases/latest/.env.example.sig
curl -LO https://get.stella-ops.org/releases/latest/docker-compose.infrastructure.yml
curl -LO https://get.stella-ops.org/releases/latest/docker-compose.infrastructure.yml.sig
curl -LO https://get.stella-ops.org/releases/latest/docker-compose.stella-ops.yml
curl -LO https://get.stella-ops.org/releases/latest/docker-compose.stella-ops.yml.sig

# 3. Verify provenance (Cosign public key is stable)
cosign verify-blob \
  --key https://stella-ops.org/keys/cosign.pub \
  --signature .env.example.sig \
  .env.example

cosign verify-blob \
  --key https://stella-ops.org/keys/cosign.pub \
  --signature docker-compose.infrastructure.yml.sig \
  docker-compose.infrastructure.yml

cosign verify-blob \
  --key https://stella-ops.org/keys/cosign.pub \
  --signature docker-compose.stella-ops.yml.sig \
  docker-compose.stella-ops.yml

# 4. Copy .env.example → .env and edit secrets
cp .env.example .env
$EDITOR .env

# 5. Launch databases (MongoDB + Redis)
docker compose --env-file .env -f docker-compose.infrastructure.yml up -d

# 6. Launch Stella Ops (first run pulls ~50 MB merged vuln DB)
docker compose --env-file .env -f docker-compose.stella-ops.yml up -d
````

*Default login:* `admin / changeme`
UI: [https://\&lt;host\&gt;:8443](https://&lt;host&gt;:8443) (self‑signed certificate)

> **Pinning best‑practice** – in production environments replace
> `stella-ops:latest` with the immutable digest printed by
> `docker images --digests`.

---

## 2 · Optional: request a free quota token

Anonymous installs allow **{{ quota\_anon }} scans per UTC day**.
Email `token@stella-ops.org` to receive a signed JWT that raises the limit to
**{{ quota\_token }} scans/day**. Insert it into `.env`:

```bash
STELLA_JWT="paste‑token‑here"
docker compose --env-file .env -f docker-compose.stella-ops.yml \
  exec stella-ops stella set-jwt "$STELLA_JWT"
```

>  The UI shows a reminder at 200 scans and throttles above the limit but will
>  **never block** your pipeline.

---

## 3 · Air‑gapped install (Offline Update Kit)

When running on an isolated network use the **Offline Update Kit (OUK)**:

```bash
# Download & verify on a connected host
curl -LO https://get.stella-ops.org/ouk/stella-ops-offline-kit-v0.1a.tgz
curl -LO https://get.stella-ops.org/ouk/stella-ops-offline-kit-v0.1a.tgz.sig

cosign verify-blob \
  --key https://stella-ops.org/keys/cosign.pub \
  --signature stella-ops-offline-kit-v0.1a.tgz.sig \
  stella-ops-offline-kit-v0.1a.tgz

# Transfer → air‑gap → import
docker compose --env-file .env -f docker-compose.stella-ops.yml \
  exec stella admin import-offline-usage-kit stella-ops-offline-kit-v0.1a.tgz
```

*Import is atomic; no service downtime.*

For details see the dedicated [Offline Kit guide](/offline/).

---

## 4 · Next steps

* **5‑min Quick‑Start:** `/quickstart/`
* **CI recipes:** `docs/ci/20_CI_RECIPES.md`
* **Plug‑in SDK:** `/plugins/`

---

*Generated {{ "now" | date: "%Y‑%m‑%d" }} — build tags inserted at render time.*