Skip to main content

Run the System

How to reach the deployed system, and how to run all of it on a workstation. The system is split across four repositories; this page ties them together.

Deployed system​

PartURLRepository
Web apphttps://oph.alonsovndev.comopen-projects-hub-web
APIhttps://api-oph.alonsovndev.com (all routes under /v1/*)open-projects-hub-api
Documentationhttps://oph-docs.alonsovndev.comthis repository
AWS infrastructure (Terraform)not publicopen-projects-hub-infra

The URLs and deployment details are recorded configuration; availability was not checked during this documentation review. For the academic reading path and a safe fictional scenario, see the reviewer guide.

To try it, open the web app, choose Register, and enter an email address you can read. The API emails a six-character code that expires after five minutes; enter it to verify the account, then sign in. Registration creates a new workspace with you as its administrator. Client Review needs no account: it uses a project's access code.

The API root and health paths are not public through Cloudflare (only /v1/* is routed), so the interactive API reference is not available in production; the committed OpenAPI file is docs/api/openapi.json in the API repository.

Ports and URLs when running locally​

ComponentCommandURL
PostgreSQLdocker compose up postgres -dlocalhost:5432
API (local Python)make runhttp://localhost:8000 (Swagger UI at /docs)
API (all in Docker)docker compose up --buildhttp://localhost:8080
Webnpm run devhttp://localhost:5173
Docs sitenpm starthttp://localhost:3000

Run the API​

Requires Python 3.12, Docker, and an isolated project environment. Follow the API repository's environment instructions before installing dependencies. From the API repository:

cp .env.example .env      # set SECRET_KEY, POSTGRES_PASSWORD, API_KEY_ENCRYPTION_KEY
make install-dev
docker compose up postgres -d
alembic upgrade head
ADMIN_EMAIL="admin@example.com" ADMIN_PASSWORD="<strong-password>" make seed-admin
make run

make seed-admin creates a verified administrator, so you can sign in without email. Registration through the UI additionally needs working SMTP settings (SMTP_* in .env, see the API repository's docs/configuration/email-deliverability.md); without them the verification email is not delivered and the account cannot be activated. GEMINI_API_KEY is optional: without it, refinement uses a mock AI service.

Run the web app​

Requires Node.js 22 (the CI version). From the web repository:

cp .env.example .env      # VITE_API_BASE_URL=http://localhost:8000
npm ci
npm run dev

If the API runs in Docker (port 8080), set VITE_API_BASE_URL=http://localhost:8080. VITE_API_BASE_URL is an origin only (no path) and is baked in at build time.

Configuration shared by the API and the web app​

VariableWherePurpose
VITE_API_BASE_URLweb .env / .env.productionAPI origin the browser calls (production: https://api-oph.alonsovndev.com)
VITE_SENTRY_DSNweb .env / Cloudflare BuildsOptional Sentry DSN for browser error tracking; its ingest origin is added to the CSP connect-src at build time. Empty disables Sentry
FRONTEND_BASE_URLAPIWeb origin (default http://localhost:5173)
CORS_ORIGINS, CORS_ALLOW_CREDENTIALSAPI (SSM in production)Allowed browser origins; credentials must be on for the refresh cookie

Verify each repository​

RepositoryCommand
APImake test-unit, ruff check ., mypy src/app --config-file=pyproject.toml
Webnpm run verify (lint, tests, type-check, build)
Docsnpm run typecheck && npm run build (broken links fail the build)
Infraterraform fmt -check -recursive and terraform validate in envs/prod

These are verification commands, not recorded results. The current API CI treats mypy as advisory and excludes the repository integration suite; web CI omits Playwright. See verification boundaries.

API integration tests (make test-integration) need PostgreSQL and reset the database they connect to; point them at a throwaway database.

Further reading​