KES Outbox E2E Runbook (15-min Onboarding)
Last updated: 2026-03-06
Purpose:
- Bring up full local KES outbox flow.
Loading module
Resolving locale, route permissions, and workspace projection.
Resolving locale, route permissions, and workspace projection.
Current scope: Guest
Category: 80_chain | Version: v1.0.0
Owner: DOCUMENT_CUSTODIAN | Review cycle: 60 days
Approval authority: GOVERNANCE_ADMIN, CHAIN_OFFICER
Documentation portal is read-only. Editing and mutation endpoints are disabled.
Kvary platform is originally created in Georgian. Where a Georgian version exists, Georgian is authoritative for platform UI, documentation, and legal interpretation.
Translations into other languages are provided for convenience. Some records may originate in other languages and carry their own source or legal locale for a specific flow, but where a Georgian version is available, the Georgian version prevails for platform-level wording and interpretation.
Metadata incomplete: Document ID, Version, Status, Owner Role, Last Review Date, Next Review Date, Change Log
Last updated: 2026-03-06
Purpose:
Target DoD:
kvary.network).Windows note:
FOO=bar cmd).cross-env where needed).Run from repo root:
npm run db:up
npm run kafka:up
npm run monitoring:up
npm run migrate:all
Then start app stack:
npm run dev:one
Open a second terminal and start outbox relay:
npm run relay:kes-outbox:dev
Expected healthy endpoints:
curl -sS http://127.0.0.1:4100/health
curl -sS http://127.0.0.1:4020/health
curl -sS http://127.0.0.1:4060/health
curl -sS "http://127.0.0.1:9090/api/v1/query?query=kes_outbox_relay_up"
Expected:
{"ok":true}{"ok":true,...}1 for kes_outbox_relay_upRun outbox live smoke:
npm run tenders:outbox:live-smoke
Expected:
"ok": trueOptional Kafka smoke:
npm run kafka:kes-smoke
Grafana dashboard:
http://localhost:3002admin / adminKES Outbox OverviewDLQ replay (consumer DLQ):
# Dry-run
npm --prefix services/svc-tenders run replay:kes-dlq -- --from-beginning --max-messages 50
# Execute
npm --prefix services/svc-tenders run replay:kes-dlq -- --execute --max-messages 50
Outbox poison replay:
# Dry-run
npm --prefix services/svc-tenders run replay:kes-outbox-poison -- --max-rows 50
# Execute
npm --prefix services/svc-tenders run replay:kes-outbox-poison -- --execute --max-rows 50
dev:one terminal (Ctrl+C).Ctrl+C).npm run monitoring:down
npm run kafka:down
docker compose -f docker-compose.postgres.yml down
EADDRINUSE (port already in use)Symptoms:
listen EADDRINUSE ... :3000/:4001/:4010/:4020/:4060/:4100Fix:
node scripts/free-port.js 3000
node scripts/free-port.js 4001
node scripts/free-port.js 4010
node scripts/free-port.js 4020
node scripts/free-port.js 4060
node scripts/free-port.js 4100
Then rerun startup command.
Symptoms:
401 /api/v1/auth/me repeats502 on auth/oidc routesChecks:
curl -sS http://127.0.0.1:4100/health
Fix:
dev:one is running.npm run dev:auth
relation ... does not exist)Symptoms:
relation "kes_outbox_events" does not existFix:
npm run migrate:all
If only tenders schema is missing:
npm --prefix services/svc-tenders run migrate
No dataChecks:
curl -sS http://127.0.0.1:4060/metrics
curl -sS "http://127.0.0.1:9090/api/v1/query?query=kes_outbox_relay_up"
Fix:
npm run relay:kes-outbox:dev)npm run monitoring:up)db + kafka + monitoring started.migrate:all completed with no errors.dev:one running.relay:kes-outbox:dev running and /health is ok:true.tenders:outbox:live-smoke returns "ok": true.KES Outbox Overview shows relay/pending/dispatch metrics.