Skip to content

local-development.md

Latest commit

 

History

History
163 lines (122 loc) · 4.73 KB

local-development.md

File metadata and controls

163 lines (122 loc) · 4.73 KB
Raw

Local Development Runbook

Last updated: 2026-06-29

Use this runbook to start Program Health Diagnostic from source with a local FastAPI backend, React/Vite frontend, SQLite database, and optional Ollama LLM.

Prerequisites

  • Python 3.12.
  • Node.js 22 or newer.
  • PowerShell.
  • Optional: Ollama with the configured model, default gemma2:latest.
  • Optional: Docker Desktop for packaged-mode validation.

Backend

Push-Location backend
python -m pip install -e .[dev]
Copy-Item .env.example .env
python -m alembic upgrade head
Pop-Location

Start the backend:

powershell -ExecutionPolicy Bypass -File scripts/Start-Backend.ps1

The API listens on http://127.0.0.1:8000. The default security mode is none, which resolves a local admin user for development. The start script loads backend/.env when it exists, applies pending Alembic migrations, then starts Uvicorn. Environment variables already set in the current shell take precedence, and script arguments such as -LlmProvider override both.

If you prefer direct process startup, use python -m uvicorn app.main:app --reload from backend/ and npm run dev from frontend/.

Frontend

Push-Location frontend
npm install
Copy-Item .env.example .env.local
Pop-Location

Start the frontend:

powershell -ExecutionPolicy Bypass -File scripts/Start-Frontend.ps1

The frontend listens on http://127.0.0.1:5173 and calls http://127.0.0.1:8000 by default.

Local Login

In the default local security mode, PGMHLTH_SECURITY_MODE=none, the backend does not read data/users/users.example.json. Sign in with any username and password. The backend will issue a local admin token for the local-dev user.

data/users/users.example.json is only a format reference for poc_users mode. To test the POC user login flow locally, create a private seed file, build the encrypted runtime artifact, and start the backend with matching secrets:

Copy-Item data/users/users.example.json data/users/users.json
# Edit data/users/users.json and replace the example password value.
$env:PGMHLTH_SECURITY_MODE = "poc_users"
$env:PGMHLTH_USER_ENCRYPTION_KEY = "local-user-artifact-key"
$env:PGMHLTH_AUTH_TOKEN_SECRET = "local-auth-token-secret"
powershell -ExecutionPolicy Bypass -File scripts/Build-UserArtifact.ps1
powershell -ExecutionPolicy Bypass -File scripts/Start-Backend.ps1

Then sign in as demo.assessor with the password you put in data/users/users.json. Keep PGMHLTH_USER_ENCRYPTION_KEY the same when building the artifact and running the backend.

LLM Modes

Disable LLM features for deterministic local work:

$env:PGMHLTH_LLM_PROVIDER = "disabled"
powershell -ExecutionPolicy Bypass -File scripts/Start-Backend.ps1 -LlmProvider disabled

Enable local Ollama:

ollama pull gemma2:latest
$env:PGMHLTH_LLM_PROVIDER = "ollama"
$env:PGMHLTH_LLM_MODEL = "gemma2:latest"
$env:OLLAMA_BASE_URL = "http://127.0.0.1:11434"
powershell -ExecutionPolicy Bypass -File scripts/Start-Backend.ps1 -LlmProvider ollama

Set PGMHLTH_LLM_MODEL to a model name shown by ollama list, for example gemma2:latest, when using a different local model.

Validation

Run focused backend checks:

Push-Location backend
python -m pytest
python -m ruff check .
Pop-Location

Run focused frontend checks:

Push-Location frontend
npm test
npm run lint
npm run build
Pop-Location

Run the local all-up verification wrapper:

powershell -ExecutionPolicy Bypass -File scripts/Test-All.ps1

Run security guardrails directly:

powershell -ExecutionPolicy Bypass -File scripts/Test-SecurityGuardrails.ps1

Troubleshooting

Port already in use: change the port with -Port on Start-Backend.ps1 or Start-Frontend.ps1, then update VITE_API_BASE_URL or CORS origins as needed.

SQLite path issues: set PGMHLTH_SQLITE_PATH to an absolute path or keep the default ../data/programhealthdiagnostic.sqlite, which resolves to the repository data/ directory.

Ollama unavailable: set PGMHLTH_LLM_PROVIDER=disabled to keep the rest of the app usable, or verify OLLAMA_BASE_URL and that the configured model appears in ollama list. A generation error like Ollama generation returned HTTP 404 usually means PGMHLTH_LLM_MODEL does not match an installed Ollama model.

Login fails in poc_users mode: rebuild data/artifacts/user/users.encrypted.json with scripts/Build-UserArtifact.ps1 and verify PGMHLTH_USER_ENCRYPTION_KEY matches the key used to create it.

Browser blocks login before credentials are checked: verify PGMHLTH_ALLOWED_ORIGINS includes the frontend origin you opened, such as http://127.0.0.1:5173 or http://localhost:5173, then restart the backend.