67225a39fa
Config policies (16 files): alert_routing, architecture_pressure, backlog, cost_weights, data_governance, incident_escalation, incident_intelligence, network_allowlist, nodes_registry, observability_sources, rbac_tools_matrix, release_gate, risk_attribution, risk_policy, slo_policy, tool_limits, tools_rollout Ops (22 files): Caddyfile, calendar compose, grafana voice dashboard, deployments/incidents logs, runbooks for alerts/audit/backlog/incidents/sofiia/voice, cron jobs, scripts (alert_triage, audit_cleanup, migrate_*, governance, schedule), task_registry, voice alerts/ha/latency/policy Docs (30+ files): HUMANIZED_STEPAN v2.7-v3 changelogs and runbooks, NODA1/NODA2 status and setup, audit index and traces, backlog, incident, supervisor, tools, voice, opencode, release, risk, aistalk, spacebot Made-with: Cursor
128 lines
4.0 KiB
Markdown
128 lines
4.0 KiB
Markdown
# Runbook: Sofiia Control Console
|
|
|
|
**Service:** sofiia-console (NODA2 primary)
|
|
**Port:** 8002
|
|
**UI:** http://localhost:8002/
|
|
|
|
---
|
|
|
|
## 1. Endpoints
|
|
|
|
| Method | Path | Auth | Description |
|
|
|--------|------|------|-------------|
|
|
| GET | `/` | — | Console UI (Chat + Ops + Nodes) |
|
|
| GET | `/api/health` | — | Aggregated health (first node router) |
|
|
| POST | `/api/chat/send` | X-API-Key* | Proxy to router `/v1/agents/sofiia/infer` |
|
|
| GET | `/api/ops/actions` | — | List ops action ids |
|
|
| POST | `/api/ops/run` | X-API-Key* | Run risk_dashboard / pressure_dashboard / backlog_generate_weekly / release_check |
|
|
| GET | `/api/nodes/dashboard` | — | Per-node router health from `config/nodes_registry.yml` |
|
|
|
|
\* If `SOFIIA_CONSOLE_API_KEY` is set, write endpoints require header `X-API-Key: <key>`.
|
|
|
|
---
|
|
|
|
## 2. Environment variables
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| `ROUTER_URL` | Default router for health/chat when node not specified | `http://localhost:9102` |
|
|
| `CONFIG_DIR` | Directory containing `nodes_registry.yml` (Docker: `/app/config`) | repo `config/` |
|
|
| `NODES_<ID>_ROUTER_URL` | Override router URL per node (e.g. `NODES_NODA1_ROUTER_URL`) | from registry |
|
|
| `SUPERVISOR_API_KEY` | Sent to router on tool/infer calls (optional) | — |
|
|
| `SOFIIA_CONSOLE_API_KEY` | Protects POST /api/chat/send and /api/ops/run | — (no auth if unset) |
|
|
|
|
---
|
|
|
|
## 3. Deploy (Docker, NODA2)
|
|
|
|
```bash
|
|
cd /path/to/microdao-daarion
|
|
docker compose -f docker-compose.node2-sofiia.yml up -d sofiia-console
|
|
```
|
|
|
|
Ensure `config/nodes_registry.yml` exists and lists `NODA1` / `NODA2` with correct `router_url`.
|
|
Open http://localhost:8002/
|
|
|
|
---
|
|
|
|
## 4. Run locally (no Docker)
|
|
|
|
```bash
|
|
cd services/sofiia-console
|
|
pip install -r requirements.txt
|
|
export ROUTER_URL=http://localhost:8000 # or 9102
|
|
uvicorn app.main:app --host 0.0.0.0 --port 8002
|
|
```
|
|
|
|
Then open http://localhost:8002/
|
|
|
|
---
|
|
|
|
## 5. API key rotation (NODA2)
|
|
|
|
Rotate both `SOFIIA_CONSOLE_API_KEY` and `SUPERVISOR_API_KEY` to one new value:
|
|
|
|
```bash
|
|
cd /Users/apple/github-projects/microdao-daarion
|
|
NEW_KEY="$(openssl rand -hex 24)"
|
|
sed -i '' "s/^SOFIIA_CONSOLE_API_KEY=.*/SOFIIA_CONSOLE_API_KEY=${NEW_KEY}/" .env
|
|
sed -i '' "s/^SUPERVISOR_API_KEY=.*/SUPERVISOR_API_KEY=${NEW_KEY}/" .env
|
|
docker compose -f docker-compose.node2-sofiia.yml up -d sofiia-console router
|
|
```
|
|
|
|
Quick check in container env:
|
|
|
|
```bash
|
|
docker exec sofiia-console sh -lc 'env | grep -E "^(ENV|SOFIIA_CONSOLE_API_KEY|SUPERVISOR_API_KEY)="'
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Ops API examples (with key)
|
|
|
|
```bash
|
|
KEY="<SOFIIA_CONSOLE_API_KEY>"
|
|
```
|
|
|
|
```bash
|
|
curl -sS -X POST http://localhost:8002/api/ops/run \
|
|
-H "X-API-Key: ${KEY}" -H "Content-Type: application/json" \
|
|
-d '{"action_id":"risk_dashboard","node_id":"NODA2","params":{}}' | jq .
|
|
```
|
|
|
|
```bash
|
|
curl -sS -X POST http://localhost:8002/api/ops/run \
|
|
-H "X-API-Key: ${KEY}" -H "Content-Type: application/json" \
|
|
-d '{"action_id":"pressure_dashboard","node_id":"NODA2","params":{}}' | jq .
|
|
```
|
|
|
|
```bash
|
|
curl -sS -X POST http://localhost:8002/api/ops/run \
|
|
-H "X-API-Key: ${KEY}" -H "Content-Type: application/json" \
|
|
-d '{"action_id":"release_check","node_id":"NODA2","params":{}}' | jq .
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Troubleshooting
|
|
|
|
| Symptom | Cause | Fix |
|
|
|---------|-------|-----|
|
|
| Chat "Помилка мережі" | Router unreachable | Check ROUTER_URL and router container |
|
|
| Ops run returns 502 | Router or tool error | Check router logs; verify RBAC for agent `sofiia` |
|
|
| Nodes dashboard empty | No nodes in registry or CONFIG_DIR wrong | Check `config/nodes_registry.yml` and CONFIG_DIR mount |
|
|
| 401 on POST /api/chat/send | API key required but missing/wrong | Set X-API-Key header to SOFIIA_CONSOLE_API_KEY or leave SOFIIA_CONSOLE_API_KEY unset |
|
|
|
|
---
|
|
|
|
## 8. Verification
|
|
|
|
After deploy, run stack verifier (from repo root):
|
|
|
|
```bash
|
|
export ROUTER_URL=http://localhost:8000 # or router:8000 inside Docker network
|
|
python3 ops/scripts/verify_sofiia_stack.py
|
|
```
|
|
|
|
See `docs/opencode/sofiia_setup.md` for OpenCode integration and tool contract.
|