7943cfb3af
Bundled pre-session doc + ops work: - docs/modules/**: sync across advisory-ai, airgap, cli, excititor, export-center, findings-ledger, notifier, notify, platform, router, sbom-service, ui, web (architectural + operational updates) - docs/features/**: updates to checked excititor vex pipeline, developer workspace, quick verify drawer - docs top-level: README, quickstart, API_CLI_REFERENCE, UI_GUIDE, code-of-conduct/TESTING_PRACTICES updates - docs/qa/feature-checks/: FLOW.md + excititor state update - docs/implplan/: remaining sprint updates + new Concelier source credentials sprint (SPRINT_20260422_003) - docs-archived/implplan/: 30 sprint archival moves (ElkSharp series, misc completed sprints) - devops/compose: .env + services compose + env example + router gateway config updates File-level granularity preserved. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
175 lines
6.7 KiB
Markdown
175 lines
6.7 KiB
Markdown
# Quickstart -- Local Dev Environment in Minutes
|
|
|
|
Get Stella Ops running locally for development and evaluation.
|
|
|
|
> This guide is for **local development**. For production deployment, see the [Installation Guide](INSTALL_GUIDE.md).
|
|
|
|
## Prerequisites
|
|
|
|
| Requirement | Minimum | Verify |
|
|
|-------------|---------|--------|
|
|
| OS | Windows 10+, macOS 12+, Ubuntu 22.04+ | x86-64 or arm64 |
|
|
| Docker | Engine 20.10+ with Compose v2 | `docker compose version` |
|
|
| .NET SDK | 10.x | `dotnet --version` |
|
|
| Node.js | 20+ | `node --version` |
|
|
| RAM | 16 GB (32 GB recommended) | |
|
|
| Disk | 50 GB free | |
|
|
|
|
## 0. Runtime data assets (optional but recommended)
|
|
|
|
Some services depend on files not produced by `dotnet build` — most notably the
|
|
ONNX embedding model for semantic search. Without it, search works but with
|
|
reduced quality.
|
|
|
|
```bash
|
|
# After cloning, download the embedding model (~80 MB)
|
|
./devops/runtime-assets/acquire.sh --models
|
|
|
|
# Verify everything is in place
|
|
./devops/runtime-assets/acquire.sh --verify
|
|
```
|
|
|
|
For binary analysis (Ghidra), add `--ghidra` (~1.6 GB). Full details:
|
|
`devops/runtime-assets/README.md`.
|
|
|
|
---
|
|
|
|
## 1. Clone the repository
|
|
|
|
```bash
|
|
git clone <your-gitea-instance>/stella-ops/stella-ops.git
|
|
cd stella-ops
|
|
```
|
|
|
|
## 2. Run setup
|
|
|
|
**Windows (PowerShell 7):**
|
|
|
|
```powershell
|
|
.\scripts\setup.ps1
|
|
```
|
|
|
|
**Linux / macOS:**
|
|
|
|
```bash
|
|
./scripts/setup.sh
|
|
```
|
|
|
|
The setup script will:
|
|
- Verify all prerequisites are installed
|
|
- Offer to add hosts file entries (50 services need unique loopback IPs)
|
|
- Create `.env` from the example template (works out of the box, no editing needed)
|
|
- Seed the local admin credential from `STELLAOPS_ADMIN_PASS` (default `Admin@Stella2026!`)
|
|
- Create or reuse the external frontdoor Docker network from `.env` (`FRONTDOOR_NETWORK`, default `stellaops_frontdoor`)
|
|
- Build .NET solutions and Docker images
|
|
- Launch the full platform stack (`docker-compose.stella-ops.yml`)
|
|
- Run health checks and report status
|
|
|
|
### Infrastructure only (faster)
|
|
|
|
To skip builds and only start infrastructure:
|
|
|
|
```powershell
|
|
.\scripts\setup.ps1 -InfraOnly # Windows
|
|
./scripts/setup.sh --infra-only # Linux/macOS
|
|
```
|
|
|
|
### Local admin credentials
|
|
|
|
The local compose template ships with:
|
|
|
|
- Username: `admin`
|
|
- Password env var: `STELLAOPS_ADMIN_PASS`
|
|
- Default local value: `Admin@Stella2026!`
|
|
|
|
Override it before running setup if you do not want the default local password:
|
|
|
|
```powershell
|
|
$env:STELLAOPS_ADMIN_PASS = 'Admin@Stella2026!'
|
|
.\scripts\setup.ps1
|
|
```
|
|
|
|
```bash
|
|
export STELLAOPS_ADMIN_PASS='Admin@Stella2026!'
|
|
./scripts/setup.sh
|
|
```
|
|
|
|
### Local UI builds that actually reach `stella-ops.local`
|
|
|
|
By default the local frontdoor serves the Angular console from the `console-dist`
|
|
Docker volume. That means a plain `ng build` can succeed while the browser still
|
|
shows the old UI bundle.
|
|
|
|
For active UI work, switch the gateway to the bind-mounted dev override once:
|
|
|
|
```powershell
|
|
cd devops/compose
|
|
docker compose -f docker-compose.stella-ops.yml -f docker-compose.dev-ui.yml up -d router-gateway
|
|
cd ../../src/Web/StellaOps.Web
|
|
npx ng build --configuration=development --watch
|
|
```
|
|
|
|
After that, refresh `https://stella-ops.local` after rebuilds. The local auth and
|
|
Playwright helpers already tolerate self-signed local certificates; keep product
|
|
runtime TLS validation strict.
|
|
|
|
## 3. First 30 minutes path
|
|
|
|
1. Start platform quickly (reuse existing images):
|
|
```powershell
|
|
.\scripts\setup.ps1 -SkipBuild -SkipImages
|
|
```
|
|
2. Confirm service health:
|
|
```powershell
|
|
docker compose -f devops/compose/docker-compose.stella-ops.yml ps
|
|
```
|
|
3. Open **https://stella-ops.local**.
|
|
4. Sign in with `admin` and the `STELLAOPS_ADMIN_PASS` value used during setup.
|
|
Default local password: `Admin@Stella2026!`.
|
|
5. If the install opens the setup wizard, continue the first-run or reconfigure flow from the authenticated session.
|
|
|
|
Optional demo datasets are manual-only and not part of the default bootstrap path. If you explicitly need them for demo purposes, use the manual seeding section in [DEV_ENVIRONMENT_SETUP.md](dev/DEV_ENVIRONMENT_SETUP.md).
|
|
|
|
## What's running
|
|
|
|
After a full setup, you'll have 60+ services running locally:
|
|
|
|
| Service | URL | Purpose |
|
|
|---------|-----|---------|
|
|
| Web UI | https://stella-ops.local | Angular console |
|
|
| Authority | https://authority.stella-ops.local | OAuth2/OIDC |
|
|
| Scanner | https://scanner.stella-ops.local | SBOM/vulnerability scanning |
|
|
| Concelier | https://concelier.stella-ops.local | Advisory aggregation |
|
|
| PostgreSQL | db.stella-ops.local:5432 | Primary database |
|
|
| Valkey | cache.stella-ops.local:6379 | Cache and messaging |
|
|
| RustFS | s3.stella-ops.local:8333 | S3-compatible object storage |
|
|
|
|
Full service list: `devops/compose/docker-compose.stella-ops.yml`
|
|
|
|
Runtime URL convention: use `*.stella-ops.local` hostnames for services.
|
|
Exception: `hosts.stellaops.local` is a file name, not a runtime host.
|
|
|
|
Optional Sigstore services (`rekor-v2`, `rekor-cli`, `cosign`) are enabled only with:
|
|
|
|
```bash
|
|
docker compose -f devops/compose/docker-compose.stella-ops.yml --profile sigstore up -d
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Meaning | Action |
|
|
|---------|---------|--------|
|
|
| `stella-ops.local` not found | Hosts entries missing | Re-run setup and accept hosts installation, or append `devops/compose/hosts.stellaops.local` manually |
|
|
| `health=starting` for RustFS during setup | Advisory startup lag | Wait 30-60 seconds and re-check `docker compose ... ps` |
|
|
| `stellaops-dev-rekor` restarting without `--profile sigstore` | Optional profile container from older runs | Non-blocking for default setup; ignore or clean old container |
|
|
| `SM remote service probe failed (localhost:56080)` in `stella --verbose ...` or crypto diagnostics | Optional China SM Remote plugin probe | Non-blocking for default crypto profile; ordinary CLI payload commands now suppress this startup noise |
|
|
| Manual demo seed endpoint still returns HTTP 500 after patching source | Running old container image | Rebuild/restart platform image and retest |
|
|
| `ng build` succeeds but `stella-ops.local` still shows the old UI | `router-gateway` is still serving the `console-dist` Docker volume | Apply `docker-compose.dev-ui.yml` with `docker compose -f devops/compose/docker-compose.stella-ops.yml -f devops/compose/docker-compose.dev-ui.yml up -d router-gateway`, then rebuild the Angular app |
|
|
| Port conflicts | Local process already using mapped port | Override in `devops/compose/.env` (`devops/compose/env/stellaops.env.example`) |
|
|
|
|
## Next steps
|
|
|
|
- [Developer setup details](dev/DEV_ENVIRONMENT_SETUP.md) -- manual steps, hybrid debugging, building individual modules
|
|
- [Installation Guide](INSTALL_GUIDE.md) -- production deployment, air-gap, regional compliance
|
|
- [Architecture overview](ARCHITECTURE_OVERVIEW.md) -- how the platform fits together
|