197 lines
7.4 KiB
Markdown
197 lines
7.4 KiB
Markdown
# 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 <https://localhost:8080> (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:<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
|
||
|
||
```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: <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)
|