Add initial documentation
This commit is contained in:
196
docs/21_INSTALL_GUIDE.md
Normal file
196
docs/21_INSTALL_GUIDE.md
Normal file
@ -0,0 +1,196 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user