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
- Audience & prerequisites
- Decide: Compose or Kubernetes
- Quick start (Compose, 5 min)
- Verifying image signatures & SBOMs
- First login & API token creation
- Optional TLS & reverse‑proxy patterns
- Kubernetes helm‑chart primer (beta)
- Configuration cheatsheet
- Upgrades & rollbacks
- Uninstall / data wipe
- Troubleshooting matrix
- Getting help
- 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)
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
export REDIS_PASS=$(openssl rand -base64 18)
echo "REDIS_PASS=$REDIS_PASS" >> .env
2.3 Launch
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
curl -k https://localhost:8080/health
# → {"redis":"OK","version":"1.5.0","commit":"5a1b7d3"}
Open https://localhost:8080 (accept self‑signed cert).
3 Verify image provenance (optional but recommended)
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
/scanendpoint responds429 Too Many Requestsand aRetry‑After: 5header. - 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
- Sign in with default admin / changeme.
- Navigate Settings → API Tokens → Generate.
- Each token inherits the 333‑scan quota by default.
- 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 β)
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
# pin digest before prod rollout
docker pull ghcr.io/stellaops/backend@sha256:<NEW_DIGEST>
docker compose up -d
# rollback
docker compose up -d backend@sha256:<OLD_DIGEST>
Minor (Y) upgrades are non‑breaking; major (X) may change CLI flags.
11 Uninstall
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: https://stella‑ops.org/docs.
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)