157 lines
5.1 KiB
Markdown
Executable File
157 lines
5.1 KiB
Markdown
Executable File
# Five‑Minute Quick‑Start ⚡
|
||
Run your first container scan locally
|
||
|
||
> **Heads‑up** – the public α `v0.1.0` image drops **late 2025**.
|
||
> Once it is published as
|
||
> `registry.stella-ops.org/stella-ops/stella-ops:0.1.0‑alpha`
|
||
> every command on this page works without changes.
|
||
|
||
---
|
||
|
||
## 0 · What you need 🔧
|
||
|
||
| Requirement | Minimum | Notes |
|
||
|-------------|---------|-------|
|
||
| OS | Ubuntu 22.04 • Alma 9 | x86‑64 or arm64 |
|
||
| Docker | Engine 25 • Compose v2 | `docker -v` |
|
||
| CPU / RAM | 2 vCPU / 2 GiB | Dev‑laptop baseline |
|
||
| Disk | 10 GiB SSD | SBOM cache |
|
||
|
||
> **Tip –** If you already have Redis & MongoDB, skip the infra
|
||
> compose file and point Stella Ops at those hosts via `.env`.
|
||
|
||
---
|
||
|
||
## 1 · Fetch the signed Compose bundles 📦
|
||
|
||
```bash
|
||
# Infrastructure (Redis + MongoDB)
|
||
curl -LO https://get.stella-ops.org/docker-compose.infrastructure.yml
|
||
curl -LO https://get.stella-ops.org/docker-compose.infrastructure.yml.sig
|
||
|
||
# Core scanner stack
|
||
curl -LO https://get.stella-ops.org/docker-compose.stella-ops.yml
|
||
curl -LO https://get.stella-ops.org/docker-compose.stella-ops.yml.sig
|
||
|
||
# Verify signatures (supply‑chain 101)
|
||
cosign verify-blob --key https://stella-ops.org/keys/cosign.pub \
|
||
--signature docker-compose.infrastructure.yml.sig docker-compose.infrastructure.yml
|
||
cosign verify-blob --key https://stella-ops.org/keys/cosign.pub \
|
||
--signature docker-compose.stella-ops.yml.sig docker-compose.stella-ops.yml
|
||
````
|
||
|
||
---
|
||
|
||
## 2 · Create `.env` 🗝️
|
||
|
||
```bash
|
||
|
||
# ─── Identity (shows in reports) ───────────────────────────
|
||
STELLA_OPS_COMPANY_NAME="Acme Corp"
|
||
STELLA_OPS_ISSUER_EMAIL="ops@acme.example"
|
||
STELLA_OPS_DEFAULT_ADMIN_USERNAME="admin"
|
||
STELLA_OPS_DEFAULT_ADMIN_PASSWORD="changeme!"
|
||
STELLA_OPS_DEFAULT_JWT="" # or load it later with
|
||
# docker --env-file .env compose -f docker-compose.stella-ops.yml exec stella set-jwt <JWT_FROM_EMAIL>
|
||
|
||
|
||
# ─── Database secrets ──────────────────────────────────────
|
||
MONGO_INITDB_ROOT_USERNAME=stella_admin
|
||
MONGO_INITDB_ROOT_PASSWORD=$(openssl rand -base64 18)
|
||
MONGO_URL=mongodb
|
||
|
||
REDIS_PASSWORD=$(openssl rand -base64 18)
|
||
REDIS_URL=redis
|
||
|
||
|
||
|
||
```
|
||
|
||
---
|
||
|
||
## 3 · Start the supporting services 🗄️
|
||
|
||
```bash
|
||
docker compose --env-file .env -f docker-compose.infrastructure.yml pull
|
||
docker compose --env-file .env -f docker-compose.infrastructure.yml up -d
|
||
```
|
||
|
||
---
|
||
|
||
## 4 · Launch Stella Ops 🚀
|
||
|
||
```bash
|
||
docker compose --env-file .env -f docker-compose.stella-ops.yml pull
|
||
docker compose --env-file .env -f docker-compose.stella-ops.yml up -d
|
||
```
|
||
|
||
*Point your browser at* **`https://<host>:8443`** – the certificate is
|
||
self‑signed in the alpha.
|
||
Default credentials: **`admin / changeme`** (rotate immediately!).
|
||
|
||
---
|
||
|
||
## 5 · Run a scan 🔍
|
||
|
||
```bash
|
||
docker compose --env-file .env -f docker-compose.stella-ops.yml \
|
||
exec stella-ops stella scan alpine:3.20
|
||
```
|
||
|
||
* First scan downloads CVE feeds (\~ 50 MB).
|
||
* Warm scans finish in **≈ 5 s** on a 4‑vCPU host thanks to the Δ‑SBOM engine.
|
||
|
||
---
|
||
|
||
## 6 · Reload or add a token later 🔄
|
||
|
||
```bash
|
||
# After adding STELLA_JWT to .env …
|
||
docker compose --env-file .env -f docker-compose.stella-ops.yml \
|
||
exec stella-ops stella jwt <JWT_FROM_EMAIL>
|
||
```
|
||
|
||
*Anonymous mode* → **{{ quota_anon }} scans/day**
|
||
*Token mode* → **{{ quota_token }} scans/day**
|
||
At **10 % of the daily max** a polite reminder appears; after {{ quota_token }} the server applies a **soft 5 s back‑off** and may return **429 + Retry‑After** until the daily reset.
|
||
|
||
---
|
||
|
||
## 7 · Typical next steps ➡️
|
||
|
||
| Task | Where to look |
|
||
| ---------------------------------------- | ------------------------------------------------------------------- |
|
||
| CI pipelines (GitHub / GitLab / Jenkins) | [`docs/ci/`](ci/) |
|
||
| Air‑gapped install | [Offline Update Kit](10_OFFLINE_KIT.md) |
|
||
| Feature overview | [20\_FEATURES.md](20_FEATURES.md) |
|
||
| Governance & licence | [`LICENSE.md`](LICENSE.md) • [`11_GOVERNANCE.md`](11_GOVERNANCE.md) |
|
||
|
||
---
|
||
|
||
## 8 · Uninstall / cleanup 🧹
|
||
|
||
```bash
|
||
docker compose --env-file .env -f docker-compose.stella-ops.yml down -v
|
||
docker compose --env-file .env -f docker-compose.infrastructure.yml down -v
|
||
rm compose-*.yml compose-*.yml.sig .env
|
||
```
|
||
|
||
---
|
||
|
||
### Licence & provenance 📜
|
||
|
||
Stella Ops is **AGPL‑3.0‑or‑later**. Every release ships:
|
||
|
||
* **Cosign‑signed** container images
|
||
* A full **SPDX 2.3** SBOM
|
||
|
||
```bash
|
||
cosign verify \
|
||
--key https://stella-ops.org/keys/cosign.pub \
|
||
registry.stella-ops.org/stella-ops/stella-ops:<VERSION>
|
||
```
|
||
|
||
---
|
||
|
||
© 2025‑2026 Stella Ops – free / libre / open‑source.
|