call-center/docs/runbooks/local-run.md

Runbook - Local Startup

1. Install dependencies:
   • python -m pip install -r requirements.txt
2. Run tests:
   • pytest -q
3. SQLite local stack:
   • python scripts/local_stack.py start
4. PostgreSQL local stack:
   • start PostgreSQL and RabbitMQ locally
   • python scripts/postgres_dev_preflight.py --env-file .env.postgres.local.template
   • python scripts/migrate_core_db.py
   • python scripts/local_stack.py start --env-file .env.postgres.local.template
   • python scripts/postgres_dev_preflight.py --env-file .env.postgres.local.template --base-url http://127.0.0.1:8080
5. Gateway URL:
   • http://localhost:8080
6. Check health:
   • GET /proxy/auth/health
7. Run Gate 1 quick check:
   • python scripts/gate1_check.py
8. Run live Gate 1/2 smoke with auto-started services:
   • python scripts/live_smoke_gate12.py
   • PostgreSQL mode: python scripts/live_smoke_gate12.py --database-url postgresql://mvp:mvp@localhost:5432/mvpcc
9. Run Gate 3 check:
   • Existing running stack: python scripts/gate3_check.py
   • Auto-start local stack: python scripts/gate3_check.py --auto-start
10. Run Gate 4 automated checks:

• python scripts/gate4_check.py
• Keep artifacts: python scripts/gate4_check.py --keep-artifacts

11. Run UAT preflight:

• Existing running stack: python scripts/uat_preflight.py --base-url http://localhost:8080
• Auto-start local stack: python scripts/uat_preflight.py --auto-start

12. Run UAT dry-run package:

• Existing running stack: python scripts/uat_dry_run.py --base-url http://localhost:8080 --update-defect-register
• Auto-start local stack: python scripts/uat_dry_run.py --auto-start --update-defect-register

13. Optional OIDC smoke-check:

• python scripts/oidc_smoke.py --base-url http://localhost:8080
• Require enterprise path enabled: python scripts/oidc_smoke.py --base-url http://localhost:8080 --require-enabled

14. Open operator UI:

• http://localhost:8080/operator

15. Optional dedicated Wave 2 shells:

• http://localhost:8080/supervisor
• http://localhost:8080/admin

16. Reset local runtime artifacts when needed:

• powershell -ExecutionPolicy Bypass -File scripts\clean_workspace.ps1

Runtime artifacts

• .data*, .local_stack, and .artifacts are regeneratable local runtime directories.
• PostgreSQL local profile keeps runtime artifacts in .data_local_pg by default.
• Use scripts/clean_workspace.ps1 to clear local DBs, logs, cached recordings, and test/runtime leftovers without touching source files or backups.

Local auth modes

• Demo/dev default:
  • OIDC_ENABLED=0
  • ALLOW_LEGACY_HEADER_AUTH=1
• Enterprise-like local validation:
  • set OIDC_ENABLED=1
  • set ALLOW_LEGACY_HEADER_AUTH=0
  • configure APP_TOKEN_SECRET, OIDC_ISSUER_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_REDIRECT_URI

See also:

• keycloak-oidc.md