Skip to content

Local Demo Runbook

Purpose: - Fast operator checklist to run a working MVP-style demo on local stack.

Prerequisites

  • .env.local exists (cp doc/operations/local-dev/env.local.example .env.local)
  • Docker running
  • jq installed
  • psql installed

Start stack

  1. Infra:
  2. make dev-infra
  3. App processes:
  4. make dev-up
  5. Verify API health:
  6. curl -fsS http://localhost:8081/api/v1/healthz | jq .

Run smoke demo script

  • bash scripts/demo_smoke.sh

What it covers: - API health - OIDC token fetch from local Keycloak - /api/v1/users/me - /api/v1/skus - /api/v1/nodes - create/get/list allocation path with demo node assignment - async transition check to active - terminal token mint + terminal websocket smoke (scripts/ws_terminal_smoke.go) - release request (active -> releasing)

Defaults and toggles: - Auto bootstrap schema+seed on fresh DB: AUTO_INIT_DB=1 (default). - Output verbosity: - DEMO_VERBOSE=0 (default) prints compact summaries for list endpoints. - DEMO_VERBOSE=1 prints full JSON payloads for deep debugging. - Keycloak token host-header alignment for local compose network: - KC_HOST_HEADER=keycloak:8080 (default). - override only if your local Keycloak issuer host differs. - Provisioning mode: - PROVISIONING_RUNTIME_MODE=noop (default in local compose) allows allocation -> active without real SSH side effects.

Optional realtime checks

  • Notifications WS:
  • connect to ws://localhost:8081/ws/notifications with subprotocols:
    • bearer
    • <access_token>
  • Terminal WS:
  • automated by scripts/demo_smoke.sh via scripts/ws_terminal_smoke.go
  • first control frame is expected to be session_ready or session_error depending on node reachability/runtime mode.

Troubleshooting

  • If OIDC token fetch fails:
  • verify Keycloak realm import finished (docker logs gpuaas-keycloak)
  • If allocation create fails:
  • ensure schema+seed applied (AUTO_INIT_DB=1 does this automatically)
  • verify DB connection: DATABASE_URL=... bash scripts/demo_smoke.sh
  • If terminal connect fails:
  • verify ENVELOPE_KEY_B64/ENVELOPE_KEY_ID and SSH host-key env vars are aligned.