# 21 · Installation & Quick‑Start Guide — **Stella Ops** *(v2.0 — 12 Jul 2025 · supersedes v1.1)* > **Scope** — Docker Compose or Kubernetes deployment of the **open‑source Core** (backend + Redis). > For Plus/Pro features (CryptoPro TLS, LDAP, OUK, Enforcement) see the private *Commercial Install Guide*. --- ##  0 Contents 0. Audience & prerequisites 1. Decide: Compose or Kubernetes 2. Quick start (Compose, 5 min) 3. Verifying image signatures & SBOMs 4. First login & API token creation 5. Optional TLS & reverse‑proxy patterns 6. Kubernetes helm‑chart primer (beta) 7. Configuration cheatsheet 8. Upgrades & rollbacks 9. Uninstall / data wipe 10. Troubleshooting matrix 11. Getting help 12. Change log --- ##  0 Audience & prerequisites | Item | Minimum | Notes | | --------- | ---------------------- | ------------------------------ | | OS | Ubuntu 22.04 or Alma 9 | x86‑64 or ARM‑64 | | CPU / RAM | 2 vCPU / 2 GB | Dev‑laptop baseline | | Disk | 10 GB SSD | SBOM + Trivy cache | | Docker | Engine 24 + Compose v2 | `docker ‑v` | | Network | HTTPS 443 open | Optional Let’s Encrypt HTTP‑01 | --- ##  1 Choose your path | Path | When to pick | Doc section | | --------------------- | ----------------------------- | ----------- | | **Docker Compose** | Single VM, PoC, laptop | § 2 | | **Kubernetes (Helm)** | Existing K3s, RKE2, EKS, etc. | § 6 | --- ##  2 Quick start — Docker Compose (5 minutes) ###  2.1 Download stack files (signed) ```bash curl -LO https://get.stellaops.org/compose-core.yml curl -LO https://get.stellaops.org/compose-core.yml.sig cosign verify-blob \ --key https://stella-ops.org/keys/cosign.pub \ --signature compose-core.yml.sig \ compose-core.yml ``` ###  2.2 Set secrets ```bash export REDIS_PASS=$(openssl rand -base64 18) echo "REDIS_PASS=$REDIS_PASS" >> .env ``` ###  2.3 Launch ```bash docker compose --env-file .env -f compose-core.yml pull docker compose --env-file .env -f compose-core.yml up -d ``` Containers pulled ✚ started in < 60 s: ghcr.io/stellaops/backend:1.5.0 redis:7.2-alpine ###  2.4 Health check ```bash curl -k https://localhost:8080/health # → {"redis":"OK","version":"1.5.0","commit":"5a1b7d3"} ``` Open (accept self‑signed cert). ##  3 Verify image provenance (optional but recommended) ```bash BACKEND_DIGEST=sha256:… # copy from `docker images --digests` cosign verify \ ghcr.io/stellaops/backend@$BACKEND_DIGEST \ --key https://stella-ops.org/keys/cosign.pub ``` SBOM lives in /usr/share/stellaops/sbom.spdx.json inside the image; auditors may ingest it directly. ## 4 Understanding the Free‑tier quota (333 scans / UTC day) Stella Ops Core is completely free to use, but to prevent abuse the backend enforces a **daily quota of 333 scans per API token**. * At **200 scans** a **yellow dashboard banner** reminds you of the limit (≈ 60 % usage). * Between **333 – 363** scans the `/scan` endpoint responds **`429 Too Many Requests`** and a **`Retry‑After: 5`** header. * Beyond **363** calls the server imposes a **hard 60 s wait‑wall** (`Retry‑After: 60`). * The counter resets at **UTC midnight**; no manual action required. * Upgrade paths: * **Self‑hosted Core** with a second API token (still 333/day). * **Plus / Pro licences** (unlimited). If you script CI pipelines, honour the `Retry‑After` header to avoid unnecessary retries. ##  6 First login & API token 1. Sign in with default **admin / changeme**. 2. Navigate **Settings → API Tokens → Generate**. 3. **Each token inherits the 333‑scan quota** by default. 4. Store the token securely in your CI secret vault. ##  7 TLS & reverse‑proxy options | Scenario | Command / config | | ------------ | --------------------------------------------------------------------------------------------------- | | Dev l | aptop Keep backend self‑signed. | | Public | VM + Let’s Encrypt Install Caddy: caddy reverse‑proxy --from stella.example.com --to localhost:8080 | | Corporate CA | Replace /certs/cert.pem + /certs/key.pem, set TLSPROVIDER=None. | ##  8 Kubernetes (Helm chart β) ```bash helm repo add stella https://charts.stella-ops.org helm install stella-core stella/core \ --set redis.password=$REDIS_PASS \ --set ingress.host=stella.example.com ``` Resources: 300 m CPU / 512 Mi backend, 128 Mi Redis. NetworkPolicy, PodSecurity & CosignVerify admission controller included. ##  9 Configuration cheatsheet (appsettings.json or env‑vars) | Key | Default | Example | | ------------------- | ----------- | ---------------------------- | | ScannerPool.Workers | 1 | SCANNERPOOL__WORKERS=4 | | FeedMerger.Cron | 0 1 ** * | FEEDMERGER__CRON="30 2 ** *" | | Redis.Password | — | REDIS__PASSWORD=$REDIS_PASS | | TlsProvider | OpenSslGost | TLSPROVIDER=None | ##  10 Upgrades & rollbacks ```bash # pin digest before prod rollout docker pull ghcr.io/stellaops/backend@sha256: docker compose up -d # rollback docker compose up -d backend@sha256: ``` Minor (Y) upgrades are non‑breaking; major (X) may change CLI flags. ##  11 Uninstall ```bash docker compose -f compose-core.yml down -v docker volume prune -f rm compose-core.yml .env ``` ##  12 Troubleshooting matrix | Symptom | Likely cause | Remedy | | -------------------- | -------------------------------------- | ----------------------------------------------------------------- | | 502 via Nginx | Backend self‑signed cert not trusted | proxy_ssl_verify off; or use proper CA | | Feed age banner red | Cron blocked by systemd time‑zone skew | Run: docker exec backend dotnet Stella.Backend feed merge | | Scan > 10 s | Cold Trivy DB | Second run should drop to < 5 s; else raise CPU / use remote mode | ##  13 Getting help * Install issues: ops@stella‑ops.org (role‑based mailbox). * Security reports: security@stella‑ops.org (GPG key available). * Community chat: Telegram @stellaopsxw. * Docs index: . ##  14 Change log | Version | Date | Notes | | ------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | | v2.0 | 2025‑07‑12 | Signed download, Cosign verification, secrets primer, TLS patterns, Helm chart, rollback steps, role‑based support addresses. | | v1.1 | 2025‑07‑11 | Original Core guide. | (End of Install Guide v2.0 — Core Edition)