# 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](/e:/Zhan/docs/runbooks/keycloak-oidc.md)