103 lines
3.3 KiB
Markdown
103 lines
3.3 KiB
Markdown
# Concelier + CLI Quickstart
|
|
|
|
This quickstart gets an operator to a working advisory ingestion loop:
|
|
- Run Concelier (advisory ingestion + deterministic normalization).
|
|
- Trigger ingestion/export jobs.
|
|
- Inspect results via the `stella` CLI.
|
|
|
|
This document stays high level and defers detailed configuration and connector behavior to the Concelier module dossier.
|
|
|
|
## 1) Prerequisites
|
|
- Deployment: follow `docs/21_INSTALL_GUIDE.md` (Compose profiles under `deploy/compose/`).
|
|
- Offline/air-gap: follow `docs/24_OFFLINE_KIT.md` and `docs/airgap/overview.md`.
|
|
- Local dev (optional): .NET SDK version pinned by `global.json`.
|
|
|
|
## 2) Run Concelier
|
|
|
|
### Option A: Run via deployment bundles (recommended)
|
|
Use the deterministic Compose profiles under `deploy/compose/` and enable Concelier in the selected profile.
|
|
|
|
Start here:
|
|
- `docs/21_INSTALL_GUIDE.md`
|
|
- `docs/modules/concelier/operations/`
|
|
|
|
### Option B: Run the service from source (dev/debug)
|
|
```bash
|
|
dotnet run --project src/Concelier/StellaOps.Concelier.WebService
|
|
```
|
|
|
|
Concelier reads `etc/concelier.yaml` by default (and supports environment overrides). See:
|
|
- `docs/modules/concelier/architecture.md`
|
|
- `docs/modules/concelier/operations/`
|
|
|
|
## 3) Configure Concelier (minimum)
|
|
1. Copy the sample config:
|
|
```bash
|
|
mkdir -p etc
|
|
cp etc/concelier.yaml.sample etc/concelier.yaml
|
|
```
|
|
2. Update storage/DSN and any connector configuration needed for your sources.
|
|
3. Keep configuration deterministic and offline-friendly (no hidden outbound calls in air-gap profiles).
|
|
|
|
Connector deep dives and operational guidance live under:
|
|
- `docs/modules/concelier/operations/connectors/`
|
|
|
|
## 4) Harden the `/jobs*` surface with Authority (recommended)
|
|
Concelier job triggers are operationally sensitive. In production-style installs, require Authority-issued tokens.
|
|
|
|
Operator entry point:
|
|
- `docs/modules/concelier/operations/authority-audit-runbook.md`
|
|
|
|
At minimum, ensure:
|
|
- Authority enforcement is enabled.
|
|
- Anonymous fallback is disabled outside controlled rollout windows.
|
|
- Any bypass CIDRs are explicitly approved and monitored.
|
|
|
|
## 5) Use the CLI for ingestion and exports
|
|
|
|
This guide uses `stella` as the CLI command name. If your packaging uses a different filename, add a local shim/symlink.
|
|
|
|
### 5.1 Point the CLI at Concelier
|
|
Set the backend base URL (example):
|
|
```bash
|
|
export STELLAOPS_BACKEND_URL="https://concelier.example.internal"
|
|
```
|
|
|
|
Authenticate using the configured Authority credentials:
|
|
```bash
|
|
stella auth login
|
|
stella auth whoami
|
|
```
|
|
|
|
See: `docs/modules/cli/guides/commands/auth.md`.
|
|
|
|
### 5.2 Trigger connector stages
|
|
Trigger a connector stage (example):
|
|
```bash
|
|
stella db fetch --source osv --stage fetch
|
|
stella db fetch --source osv --stage parse
|
|
stella db fetch --source osv --stage map
|
|
```
|
|
|
|
### 5.3 Reconcile merges (when needed)
|
|
```bash
|
|
stella db merge
|
|
```
|
|
|
|
### 5.4 Produce exports
|
|
```bash
|
|
stella db export --format json
|
|
```
|
|
|
|
See: `docs/modules/cli/guides/commands/db.md`.
|
|
|
|
### 5.5 Inspect advisory results
|
|
For read-only inspection (list/get/export), use:
|
|
- `docs/modules/cli/guides/commands/advisory.md`
|
|
|
|
## 6) Next links
|
|
- Concelier module dossier: `docs/modules/concelier/README.md`
|
|
- Concelier operations: `docs/modules/concelier/operations/`
|
|
- CLI command guides: `docs/modules/cli/guides/commands/`
|
|
- API + CLI reference index: `docs/09_API_CLI_REFERENCE.md`
|