Run the web app locally

Run the web application locally when you want to change the UI, API, or database. You can use the hosted web app with a local agent without completing this chapter.

Install dependencies

Use Node.js 20 and npm, matching the repository CI, and a PostgreSQL database. From the repository root:

npm ci
cp .env.example .env

On Windows PowerShell, use Copy-Item .env.example .env. If an environment file already exists, update it instead of overwriting it. Use .env for this walkthrough so both Prisma and Next.js read the same configuration; Next.js can override it with .env.local values.

Configure authentication

Set DATABASE_URL and AUTH_SECRET. Generate a secret with:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Paste the output into AUTH_SECRET in .env. For personal Google sign-in, configure GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, with this authorized redirect URI in your Google OAuth application:

http://localhost:3000/api/auth/callback/google

The seeded demo has a separate sign-in provider. The RESEND_* variables and SUPPORT_TO are optional for the support form.

Start PostgreSQL

For an isolated local database, run this single-line command:

docker run --name healthcam-db -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=healthcam -p 127.0.0.1:5432:5432 -d postgres:16

Use this development-only connection string in .env:

DATABASE_URL="postgresql://postgres:postgres@127.0.0.1:5432/healthcam"

Check readiness, then apply migrations and generate the Prisma client:

docker exec healthcam-db pg_isready -U postgres -d healthcam
npx prisma migrate deploy
npx prisma generate

Seed and launch

Use a dedicated development database. Seeding replaces demo telemetry and clears/rebuilds the shared BPM summary table from stored payloads.

npm run db:seed
npm run dev

Open localhost:3000 and choose Explore the demo on Login. The seed creates the catalogue, a read-only demo user, synthetic telemetry, and aggregates through the repository's SQL processing path.

For real agent uploads, sign in with your own Google account and generate an API key in Settings. Add the BPM dashboard from the Store if you plan to collect BPM results.

Connect your local agent

The agent's configuration is a separate healthcam-agent/.env file:

CLOUD_API_KEY="your-local-workspace-key"
NEXTJS_API_URL="http://host.docker.internal:3000/api/recordings/payloads"

The orchestrator runs in Docker and reaches the host through host.docker.internal. Verify that the web server is listening on an interface Docker can reach. The dashboard browser reaches the agent at http://127.0.0.1:8008 by default; set NEXT_PUBLIC_LOCAL_AGENT_URL in the web environment if you change that address.

Refresh dashboard data

The development server does not run scheduled GitHub Actions. After uploading valid BPM telemetry, run:

npx prisma db execute --file prisma/scripts/refresh_bpm_daily_summary_incremental.sql --schema prisma/schema.prisma

To reconcile the recent window, run:

npx prisma db execute --file prisma/scripts/refresh_bpm_daily_summary.sql --schema prisma/schema.prisma

The incremental workflow is scheduled every five minutes and the reconciliation workflow at 02:10 UTC. Deployments do not make these jobs run against a new database automatically; the workflows use their repository DATABASE_URL secret.

Run the software checks

npm run typecheck
npm run lint
npm test
npm run build

Vitest covers payload validation and ingestion responses with a mocked database. CI also runs linting, type checking, and a production build. These checks do not exercise your physical camera, GPU, SQL integration, or desktop permissions. Use the first-test guide for that manual integration path.