git.stella-ops.org/docs/21_INSTALL_GUIDE.md

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)

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 /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 β)

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)