Initial commit (history squashed)

docs/03_QUICKSTART.md

@@ -0,0 +1,156 @@
+# 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.