# Five‑Minute Quick‑Start ⚡  
Run your first container scan locally

> **Heads‑up** – the public α `v0.1.0` image drops **late 2025**.  
> Once it is published as  
> `registry.stella-ops.org/stella-ops/stella-ops:0.1.0‑alpha`  
> every command on this page works without changes.

---

## 0 · What you need 🔧

| Requirement | Minimum | Notes |
|-------------|---------|-------|
| OS | Ubuntu 22.04 • Alma 9 | x86‑64 or arm64 |
| Docker | Engine 25 • Compose v2 | `docker -v` |
| CPU / RAM | 2 vCPU / 2 GiB | Dev‑laptop baseline |
| Disk | 10 GiB SSD | SBOM cache |

> **Tip –** If you already have Redis & MongoDB, skip the infra
> compose file and point Stella Ops at those hosts via `.env`.

---

## 1 · Fetch the signed Compose bundles 📦

```bash
# Infrastructure (Redis + MongoDB)
curl -LO https://get.stella-ops.org/docker-compose.infrastructure.yml
curl -LO https://get.stella-ops.org/docker-compose.infrastructure.yml.sig

# Core scanner stack
curl -LO https://get.stella-ops.org/docker-compose.stella-ops.yml
curl -LO https://get.stella-ops.org/docker-compose.stella-ops.yml.sig

# Verify signatures (supply‑chain 101)
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
````

---

## 2 · Create `.env` 🗝️

```bash

# ─── Identity (shows in reports) ───────────────────────────
STELLA_OPS_COMPANY_NAME="Acme Corp"
STELLA_OPS_ISSUER_EMAIL="ops@acme.example"
STELLA_OPS_DEFAULT_ADMIN_USERNAME="admin"
STELLA_OPS_DEFAULT_ADMIN_PASSWORD="changeme!"
STELLA_OPS_DEFAULT_JWT=""  # or load it later with
# docker --env-file .env compose -f docker-compose.stella-ops.yml exec stella set-jwt <JWT_FROM_EMAIL>


# ─── Database secrets ──────────────────────────────────────
MONGO_INITDB_ROOT_USERNAME=stella_admin
MONGO_INITDB_ROOT_PASSWORD=$(openssl rand -base64 18)
MONGO_URL=mongodb

REDIS_PASSWORD=$(openssl rand -base64 18)
REDIS_URL=redis


    
```

---

## 3 · Start the supporting services 🗄️

```bash
docker compose --env-file .env -f docker-compose.infrastructure.yml  pull
docker compose --env-file .env -f docker-compose.infrastructure.yml  up -d
```

---

## 4 · Launch Stella Ops 🚀

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

*Point your browser at* **`https://<host>:8443`** – the certificate is
self‑signed in the alpha.
Default credentials: **`admin / changeme`** (rotate immediately!).

---

## 5 · Run a scan 🔍

```bash
docker compose --env-file .env -f docker-compose.stella-ops.yml \
  exec stella-ops stella scan alpine:3.20
```

* First scan downloads CVE feeds (\~ 50 MB).
* Warm scans finish in **≈ 5 s** on a 4‑vCPU host thanks to the Δ‑SBOM engine.

---

## 6 · Reload or add a token later 🔄

```bash
# After adding STELLA_JWT to .env …
docker compose --env-file .env -f docker-compose.stella-ops.yml \
  exec stella-ops stella jwt <JWT_FROM_EMAIL>
```

*Anonymous mode* → **{{ quota_anon }} scans/day**  
*Token mode* → **{{ quota_token }} scans/day**  
At **10 % of the daily max** a polite reminder appears; after {{ quota_token }} the server applies a **soft 5 s back‑off** and may return **429 + Retry‑After** until the daily reset.

---

## 7 · Typical next steps ➡️

| Task                                     | Where to look                                                       |
| ---------------------------------------- | ------------------------------------------------------------------- |
| CI pipelines (GitHub / GitLab / Jenkins) | [`docs/ci/`](ci/)                                                   |
| Air‑gapped install                       | [Offline Update Kit](10_OFFLINE_KIT.md)                             |
| Feature overview                         | [20\_FEATURES.md](20_FEATURES.md)                                   |
| Governance & licence                     | [`LICENSE.md`](LICENSE.md) • [`11_GOVERNANCE.md`](11_GOVERNANCE.md) |

---

## 8 · Uninstall / cleanup 🧹

```bash
docker compose --env-file .env -f docker-compose.stella-ops.yml down -v
docker compose --env-file .env -f docker-compose.infrastructure.yml  down -v
rm compose-*.yml compose-*.yml.sig .env
```

---

### Licence & provenance 📜

Stella Ops is **AGPL‑3.0‑or‑later**. Every release ships:

* **Cosign‑signed** container images
* A full **SPDX 2.3** SBOM

```bash
cosign verify \
  --key https://stella-ops.org/keys/cosign.pub \
  registry.stella-ops.org/stella-ops/stella-ops:<VERSION>
```

---

© 2025‑2026 Stella Ops – free / libre / open‑source.