Skip to content

Local Setup ​

Everything you need to go from a clean machine to a running PPP stack — frontend at http://localhost:3000, backend tRPC API at http://localhost:4000, talking to the shared dev Postgres — in about 20–30 minutes.

TL;DR

bash
# 1. Prereqs: Node 22+, pnpm 9+, git, openssl
git clone https://github.com/Professional-Performance-Portfolio/ppp.git
cd ppp
pnpm install
pnpm build

# 2. Generate a backend .env with HMAC secrets pre-filled
bash api/backend-ppp/scripts/setup-local-env.sh
# Then edit api/backend-ppp/.env — fill in DATABASE_URL, STRIPE_*, GEMINI_API_KEY,
# AZURE_STORAGE_* from the team (Doppler `ppp/share`).

# 3. Copy the frontend env sample (defaults point at localhost:4000)
cp instances/ppp/.env.sample instances/ppp/.env

# 4. Run both sides — in two terminals
cd api/backend-ppp && pnpm start         # :4000
cd instances/ppp && pnpm start           # :3000

Open http://localhost:3000, log in as admin@sample.com, open the Dashboard. If the CPD tile loads without spinning forever, the frontend, backend, and DB are all wired correctly.

This page is the human getting-started guide. It links out to the authoritative deep-dive docs for each subsystem instead of re-stating them — so when a detail changes, you read it from the source of truth, not a stale copy.

For the full AI / agent convention file (commit style, BDD-first rule, verification gates, no-any policy, etc.) see the root CLAUDE.md. This page deliberately does not duplicate it.

1. Prerequisites ​

Install these before you clone. Versions matter — older Node or pnpm will fail the pnpm install turbo build step with confusing errors.

ToolVersionWhyInstall
Node.js>= 22.14.0Enforced by package.json#engines. Turbo + Vite 7 need native fetch.nodejs.org or nvm install 22
pnpm>= 9Workspace resolver. npm install will not work in this monorepo.corepack enable && corepack prepare pnpm@latest --activate
gitany modernObvious.git-scm.com
opensslanyUsed by setup-local-env.sh to generate HMAC token signing secrets.Pre-installed on macOS/Linux; on Windows use Git Bash or WSL2
GitHub org accessmemberThe repo is private, and some npm packages come from @moreton-blue-software. You need a read:packages PAT set as NPM_TOKEN for pnpm install to succeed.Ask Matt for an invite + create a classic PAT with read:packages scope
Doppler CLI (optional)latestPulls shared secrets (TEST_DATABASE_URL, Stripe test keys, Gemini, Azure Storage) from the ppp/share config without copy-pasting.docs.doppler.com/docs/install-cli
Azure CLI (optional)latestOnly needed if you want to read UAT/prod secrets straight from Azure Key Vault (ppp-uk-uat-kv) instead of Doppler.aka.ms/azcli
Docker (optional)latestOnly needed if you want a throwaway local Postgres instead of sharing the dev DB. The default flow uses the shared dev DB.docker.com
Stripe CLI (optional)latestNeeded if you are developing payment flows and want to forward webhooks to localhost:4000.stripe.com/docs/stripe-cli

Windows users

Use WSL2 or Git Bash for all bash commands on this page. The setup-local-env.sh script uses sed -i and openssl rand -hex, neither of which work in stock PowerShell.

2. Clone and install ​

bash
git clone https://github.com/Professional-Performance-Portfolio/ppp.git
cd ppp

# Set the npm token for @moreton-blue-software packages
export NPM_TOKEN=ghp_yourTokenHere   # or add to ~/.npmrc

pnpm install
pnpm build

What pnpm build does: Runs the turbo pipeline — builds every shared package (packages/*, packages-shared/ppp/*), then the two backend apps, then generates the tRPC type bundles consumed by the frontend. You must run this at least once before pnpm start or the frontend will fail to resolve ~ppp-core/* and ~ppp-api/* type imports.

Build shortcuts:

bash
pnpm build          # Everything (packages + core + types)
pnpm build:pkgs     # Only packages/* (fast path when iterating on a package)
pnpm build:types    # Only generated API types
pnpm build:force    # Ignore turbo cache — use when a stale cache is lying to you

If a build is misbehaving and you suspect stale cache:

bash
pnpm remove-turbo-cache
pnpm clean          # Nuclear: wipes every node_modules and build artifact
pnpm install
pnpm build:force

2.1 Git hooks (Husky) ​

pnpm install installs Husky and wires up the git hooks in .husky/. You do not need to do anything extra — the hooks activate automatically after install.

HookWhen it runsWhat it does
pre-commitBefore every commitRuns lint-staged (ESLint + Prettier on staged files), spec-drift check, prototype-drift check, test-file naming check for staged *.test.ts files, and feature-graph DAG validation for staged *.feature files.
pre-pushBefore every pushRuns tsc on packages with changed files. If docs/features/*.md is in the push, regenerates and prettier-fixes the derived files (docs/features/README.md, docs/site/features/index.md, docs/site/.vitepress/cache/features-counts.json) and fails the push if they are out of date — prompting you to commit the regen output before retrying.
post-mergeAfter every git mergeIf docs/features/*.md changed in the merge, re-runs sync-features + prettier on the derived files and shows which files need staging. If pnpm-lock.yaml or package.json changed, reminds you to run pnpm install && pnpm build.

Bypassing hooks ​

All hooks check HUSKY=0 first. Prefix any git command with HUSKY=0 to skip all hooks in an emergency:

bash
HUSKY=0 git commit -m "emergency fix"
HUSKY=0 git push

Do not make this a habit — CI is the authoritative gate, but skipping hooks increases round-trip times when CI catches what the hook would have.

Fresh worktrees and node_modules ​

Hooks that need node_modules (lint-staged, turbo tsc, prettier, tsx) soft-skip with a warning when node_modules is absent. This is normal in a freshly-checked-out worktree — run pnpm install in the worktree root if you want the full fast-fail experience locally.

3. Environment files ​

There are three .env.sample files to care about. Each lives next to the app that reads it, and each has a slightly different story for how you get real values.

FileUsed byFill from
instances/ppp/.env.sampleVite dev server (frontend)Copy as-is. Defaults point at http://localhost:4000 for the backend — only edit if you are pointing at UAT instead of local.
api/backend-ppp/.env.sampletRPC dev server (backend)Run bash api/backend-ppp/scripts/setup-local-env.sh once, then fill the REPLACE_ME values from Doppler ppp/share or Azure KV.
.env.sample (repo root)Tooling: Grafana, GitHub CLI, npmOnly needed if you are running infra/CI scripts locally. Safe to skip for normal app development.

3.1 Frontend env — instances/ppp/.env ​

bash
cp instances/ppp/.env.sample instances/ppp/.env

That's it. The defaults are correct for local development:

VariableDefaultMeaning
VITE_BETTER_AUTH_BASE_URLhttp://localhost:4000/api/authBetter Auth (session cookies, sign-in, sign-up) endpoint on the local backend
VITE_APP_TRPC_URLhttp://localhost:4000/trpctRPC root URL. Change to https://api-uat.professionalperformanceportfolio.com/trpc to point at UAT instead of local backend
VITE_ALLOWED_HOST(empty)Optional Vite allowedHosts entry for tunnel/remote dev (ngrok etc.)
VITE_FHIR_BASE_URLhttps://r4.ontoserver.csiro.au/fhirCSIRO Ontoserver — SNOMED CT terminology server used by the CPD tagger
VITE_FHIR_SYSTEM_VERSIONSNOMED CT AU edition, 2025-06-30Pins the SNOMED release so procedure codes stay stable between dev and prod
VITE_OFFLINE_MODEfalseWhen true, the SPA uses a cached empty response set and skips backend calls entirely
VITE_DEFAULT_COUNT50Default page size for paginated lists

3.2 Backend env — api/backend-ppp/.env ​

Never hand-edit .env.sample — always work in your own .env. Use the bootstrap script so the three HMAC token signing secrets get auto-generated:

bash
bash api/backend-ppp/scripts/setup-local-env.sh

The script:

  1. Copies .env.sample → .env (and bails out if .env already exists, so you never clobber existing secrets).
  2. Runs openssl rand -hex 32 to fill CPD_APPROVAL_SECRET, SECRET_360_KEY, and TIMESHEET_BATCH_SECRET. These are HMAC-SHA256 signing keys, not credentials for any external service — any random string works locally.
  3. Prints a list of the remaining REPLACE_ME lines so you know exactly what is still outstanding.

Then fill in the real values. Every secret's source is named explicitly — no "see the sample file" handwaves:

VariableSourceNotes
DATABASE_URLAsk the team, or doppler secrets get DATABASE_URL --config ppp/dev --plain. For the UAT DB, az keyvault secret show --vault-name ppp-uk-uat-kv --name DATABASE-URL --query value -o tsvDefaults to the shared dev Postgres. Never point local against UAT/prod for destructive testing.
TEST_DATABASE_URLdoppler secrets get TEST_DATABASE_URL --config ppp/share --plainOnly used when NODE_ENV=test (i.e. pnpm test). CI overrides this with a local Postgres spun up in GH Actions.
STORAGE_PROVIDERLeave as azure-blobSet to s3 only for the legacy AWS path
AZURE_STORAGE_ACCOUNTDoppler ppp/share → AZURE_STORAGE_ACCOUNT — or Azure KV ppp-uk-uat-kvProfile picture / CV / document uploads fail silently if left as REPLACE_ME
AZURE_STORAGE_ACCOUNT_KEYDoppler ppp/share → AZURE_STORAGE_ACCOUNT_KEY—
AZURE_STORAGE_CONTAINERuploadsMatches the UAT container name
STORAGE_KEY_PREFIXppp-devNamespaces your local uploads so they do not collide with teammates'
GEMINI_API_KEYDoppler ppp/share → GEMINI_API_KEYRequired for the sticker OCR flow in the CPD logger
STRIPE_SECRET_KEY / STRIPE_PUBLISHABLE_KEYDoppler ppp/share → STRIPE_SECRET_KEY_TEST / STRIPE_PUBLISHABLE_KEY_TESTAlways use test-mode keys locally (sk_test_…, pk_test_…)
STRIPE_WEBHOOK_SECRETRun stripe listen --forward-to localhost:4000/webhooks/stripe and copy the whsec_… value it printsOnly needed if you are working on the Stripe webhook handler
SEND_GRID_API_KEYDoppler ppp/share → SEND_GRID_API_KEYLeave as REPLACE_ME if you are not testing email sends — the mailer logs instead
XERO_CLIENT_ID / XERO_CLIENT_SECRETDoppler ppp/share — ask before usingOnly needed for Xero invoice sync work
WHOOP_CLIENT_ID / WHOOP_CLIENT_SECRETDoppler ppp/share → WHOOP_CLIENT_ID / WHOOP_CLIENT_SECRETWellness wearable integration. Redirect URI is http://localhost:3000/wellness/whoop/callback
FITBIT_CLIENT_ID / FITBIT_CLIENT_SECRETDoppler ppp/shareWellness wearable integration
GOOGLE_FIT_CLIENT_ID / GOOGLE_FIT_CLIENT_SECRETDoppler ppp/shareWellness wearable integration
BETTER_AUTH_BASE_URLhttp://localhost:3000Leave as localhost for local dev. Set BETTER_AUTH_COOKIE_DOMAIN=.professionalperformanceportfolio.com in UAT/prod only
WEB_APP_BASE_URLhttp://localhost:3000Used to build approval/review links inside outgoing emails
CPD_APPROVAL_SECRET / SECRET_360_KEY / TIMESHEET_BATCH_SECRETAuto-generated by setup-local-env.shHMAC signing secrets for approval-link tokens — never share these between environments
REDIS_URLredis://localhost:6379Devcontainer ships a redis:7-alpine on this port. Set SKIP_REDIS=1 to disable cache entirely

For the canonical per-variable reference (including TTLs, secret lineage, and production injection paths) see docs/site/development/backend/environment.md — authoritative for backend env vars.

3.3 Fetching secrets from Azure Key Vault ​

If you cannot use Doppler, you can pull the UAT secret values directly from Key Vault. You need to be a member of the PPP Azure AD group and logged in via az login:

bash
az login
az account set --subscription <ppp-subscription-id>

# List all secrets in the UAT vault
az keyvault secret list --vault-name ppp-uk-uat-kv -o table

# Read a specific value
az keyvault secret show --vault-name ppp-uk-uat-kv --name DATABASE-URL --query value -o tsv
az keyvault secret show --vault-name ppp-uk-uat-kv --name STRIPE-SECRET-KEY --query value -o tsv
az keyvault secret show --vault-name ppp-uk-uat-kv --name GEMINI-API-KEY --query value -o tsv

Full Key Vault inventory, RBAC model, and the rationale for why secrets are injected as Container App env vars (rather than Key Vault references) live in docs/ppp-azure-uat-infrastructure.md — authoritative for Azure secret sourcing.

4. Database ​

PPP runs on PostgreSQL via Drizzle ORM. For local dev you have two options.

Fastest path — no Postgres install, no migrations to run, real seed data (users, hospitals, CPD plan templates) already present. Get the DATABASE_URL value from Doppler ppp/dev and paste into api/backend-ppp/.env. Done.

Be kind to teammates: the dev DB is shared. Do not truncate tables, do not run destructive scripts, and prefix any test data you create with your initials so others can tell it apart.

4.2 Option B: Run Postgres locally in Docker ​

Useful when you are testing migrations or schema changes and do not want to affect the shared DB.

bash
docker run --name ppp-pg \
  -e POSTGRES_USER=ppp \
  -e POSTGRES_PASSWORD=ppp \
  -e POSTGRES_DB=ppp \
  -p 5432:5432 \
  -d postgres:16

# In api/backend-ppp/.env:
# DATABASE_URL=postgresql://ppp:ppp@localhost:5432/ppp?sslmode=disable

Then run the Drizzle migrations to create the schema:

bash
cd packages-shared/ppp
pnpm db:migrate

Seed the admin@sample.com test user (needed to log in at all):

bash
cd api/backend-ppp
INSTANCE_ID=pppDev pnpm tsx scripts/seedAdminUser.ts

Optional — seed master data (procedures, hospitals, CPD plan templates, specialties) so the app isn't empty:

bash
cd api/backend-ppp
INSTANCE_ID=pppDev pnpm tsx scripts/seedBootstrap.ts
INSTANCE_ID=pppDev pnpm tsx scripts/seedSettingsData.ts
INSTANCE_ID=pppDev pnpm tsx scripts/seedCpdPlanTemplates.ts

4.3 Schema, migrations, and queries ​

  • Drizzle schema: packages-shared/ppp/src/schema.ts — every column in every PPP table
  • Zod validators: packages-shared/ppp/src/zodSchema.ts — runtime validation that mirrors the schema
  • Migration files: packages-shared/ppp/drizzle/*.sql — always committed in the same PR as the schema change. Every new migration NNNN_tag.sql ships with a sibling NNNN_tag.validate.sql validator that runs in CD post-drizzle-kit migrate (see CLAUDE.md "Don't add columns… without a migration" for the full rule)
  • Ad-hoc SQL debugging: run pnpm debug __debug__/templates/pg-client-sample.ts from api/backend-core/ and edit the template file with your query. The full PgClient debug pattern is documented in api/backend-core/CLAUDE.md — authoritative for core DB debugging

5. Running the frontend ​

bash
cd instances/ppp
pnpm start
  • Serves on http://0.0.0.0:3000
  • Hot-reloads on file save (Vite HMR)
  • Talks to VITE_APP_TRPC_URL (default http://localhost:4000/trpc) — so the backend must be running or every page that makes an API call will show a loading spinner forever
  • To point the frontend at UAT instead of local: set VITE_APP_TRPC_URL=https://api-uat.professionalperformanceportfolio.com/trpc and VITE_BETTER_AUTH_BASE_URL=https://api-uat.professionalperformanceportfolio.com/api/auth in instances/ppp/.env, then restart pnpm start

For the full frontend dev workflow (Storybook, tests with UI, memory-bank conventions), see instances/ppp/README.md and the PPP memory bank — authoritative for frontend dev workflow.

6. Running the backend ​

bash
cd api/backend-ppp
pnpm start
  • Serves on http://localhost:4000
  • Health check at GET /ping — returns 200 OK from the dev server (createDevServer in api/backend-core/src/utils/server.ts). The production container entrypoint (api-container.ts) also exposes /healthz, but /healthz is not registered by pnpm start / api-dev.ts
  • Auto-restarts on file save (tsx watcher)
  • Set DEBUG_LOGS=1 to see every tRPC request/response in the terminal

Running in test mode (uses TEST_DATABASE_URL and loads .env.test):

bash
cd api/backend-ppp
pnpm debug     # same as pnpm start but with NODE_ENV=test + dotenvx

Running the test suite:

bash
cd api/backend-ppp
pnpm test              # one-shot
pnpm test:watch        # watch mode
pnpm test:ci           # CI mode with coverage

Backend test patterns, service-method-vs-tRPC-procedure testing rules, and the createInnerContext helper are all documented in api/backend-ppp/CLAUDE.md — authoritative for backend test patterns and pnpm debug.

7. Authentication locally ​

PPP uses Better Auth for session management, backed by the PPP Postgres user and session tables. There is no Azure AD B2C in the local flow.

Logging in with the seeded admin ​

After running the admin seed script (see §4.2) you have an admin@sample.com user with a known password. Use that to log in on the local signup page:

  1. Open http://localhost:3000
  2. Click Sign in
  3. Email: admin@sample.com, password: 12345Qwerty@ (default hard-coded in seedAdminUser.ts). Override with SEED_ADMIN_PASSWORD=… INSTANCE_ID=pppDev pnpm tsx scripts/seedAdminUser.ts if you need a custom one — never use this account against UAT or production.

Better Auth sets an HTTP-only better-auth.session-token cookie scoped to localhost. In local dev, BETTER_AUTH_COOKIE_DOMAIN must be unset so the cookie defaults to the current host. In UAT/prod it is set to .professionalperformanceportfolio.com so the API (api-uat.…) and the frontend (ppp-uat.…) share a session across subdomains.

If your session "logs you out on every request": confirm BETTER_AUTH_COOKIE_DOMAIN is unset in your local .env and that you are hitting the app via http://localhost:3000 (not 127.0.0.1).

Test accounts in UAT ​

If you need to sign in against UAT with known test personas (e.g. for e2e reproduction), the full list of seeded test accounts is in docs/site/development/test-accounts.md.

8. Golden-path verification ​

Run this exact flow after your first setup. If every step works, your frontend, backend, and database are all wired up correctly.

  1. Backend is alive. In one terminal: cd api/backend-ppp && pnpm start. In another: curl http://localhost:4000/ping — expect a 200 response. (/healthz only exists in the production container entrypoint, not the dev server.)
  2. Frontend is alive. cd instances/ppp && pnpm start. Open http://localhost:3000 — expect the PPP marketing/landing or sign-in screen without a "Failed to fetch" banner.
  3. Sign in works. Sign in as admin@sample.com. You should land on the Dashboard without being bounced back to the sign-in page. If you bounce: see §7 (cookie domain) and §9 (port conflicts).
  4. tRPC round-trip works. On the Dashboard, the CPD tile should populate with plan data. Watch the backend terminal — you should see a trpc.ppp.getCurrentUser and one or more trpc.ppp.cpd.* calls logged. This proves frontend → backend → Postgres is connected end-to-end.
  5. Write path works. Navigate to CPD → My Plan, click Add Activity, fill in a placeholder activity, save. The activity should appear in the list immediately. In the DB, SELECT * FROM ppp_activity ORDER BY "createdAt" DESC LIMIT 1; should show your new row.

If step 4 or 5 fails, the DB credentials in api/backend-ppp/.env are almost certainly wrong — double-check DATABASE_URL by running psql "$DATABASE_URL" -c 'SELECT now();'.

9. Common problems ​

The top gotchas, in order of how often they bite new engineers.

9.1 "Cannot find module ~ppp-core/…" on frontend start ​

Symptom: Vite fails to import tRPC types. Frontend does not start or shows a red overlay.

Cause: You ran pnpm start before pnpm build. The frontend imports generated types from the shared packages and they don't exist yet.

Fix:

bash
pnpm build       # From repo root
# Then retry pnpm start in instances/ppp

9.2 pnpm install fails with 401 / 403 on @moreton-blue-software/* ​

Symptom: npm ERR! 401 Unauthorized - GET https://npm.pkg.github.com/...

Cause: No NPM_TOKEN, or the PAT does not have read:packages scope, or the GitHub account behind the PAT is not a member of @moreton-blue-software.

Fix: Create a classic PAT at github.com/settings/tokens with read:packages scope, export it: export NPM_TOKEN=ghp_…, then re-run pnpm install. Or add //npm.pkg.github.com/:_authToken=ghp_… to ~/.npmrc.

9.3 "Wrong Node version" or weird turbo crash ​

Symptom: Error: Cannot read properties of undefined (reading 'startsWith') deep in a node_modules bin, or turbo segfaults during build.

Cause: You are on Node < 22. Check with node --version.

Fix:

bash
nvm install 22
nvm use 22
pnpm clean && pnpm install && pnpm build:force

9.4 Frontend loads but every API call hangs ​

Symptom: Dashboard shows a spinner forever. Network tab shows pending POST /trpc/… requests.

Cause: The backend isn't running, or you changed VITE_APP_TRPC_URL to a non-reachable URL, or something else is bound to port 4000.

Fix:

bash
# Is the backend up?
curl http://localhost:4000/healthz

# Is port 4000 bound by the right process?
lsof -iTCP:4000 -sTCP:LISTEN     # macOS/Linux
netstat -ano | findstr :4000     # Windows

# If port is bound by an orphan process, kill it and restart the backend

9.5 Backend throws "CPD_APPROVAL_SECRET is not set" on startup ​

Symptom: Backend process exits immediately with a thrown Error about CPD_APPROVAL_SECRET, SECRET_360_KEY, or TIMESHEET_BATCH_SECRET.

Cause: You copied .env.sample manually instead of running setup-local-env.sh, so the three HMAC secrets are still REPLACE_ME.

Fix:

bash
rm api/backend-ppp/.env
bash api/backend-ppp/scripts/setup-local-env.sh

The script regenerates the secrets with openssl rand -hex 32. Then re-fill the external-service REPLACE_ME values you had before.

9.6 Stale turbo cache / "I know I fixed this" ​

Symptom: A change you know you made has no effect. A package seems to be rebuilt from a previous version.

Cause: Turbo is serving a cached build from before your change. Happens most often after rebases or when a generated file changes.

Fix:

bash
pnpm remove-turbo-cache
pnpm build:force

If that still doesn't work, the nuclear option is pnpm clean && pnpm install && pnpm build:force.

9.7 "Relation does not exist" or "column does not exist" from backend ​

Symptom: Any tRPC call that hits a given table returns a Postgres error about a missing table or column.

Cause: Drizzle schema has a column that the database does not. Either you are pointing at a DB that has not had recent migrations applied, or a teammate's PR added a column without shipping the migration file (this caused incident #4379 — that's why CI now has a migration-check gate).

Fix: If you are on the shared dev DB, pull origin/uat and pnpm install — migrations run automatically in dev. If you are on a local Docker Postgres, cd packages-shared/ppp && pnpm db:migrate. If the problem is your own PR, run cd packages-shared/ppp && pnpm db:generate and commit the generated drizzle/NNNN_tag.sql + sibling .validate.sql file alongside your schema change.

9.8 Key Vault access denied ​

Symptom: az keyvault secret show returns 403 Forbidden.

Cause: You are logged in with az login but your account is not a member of the PPP Azure AD group that has Key Vault Secrets User role on ppp-uk-uat-kv.

Fix: Ask Matt to add you to the group. As a stopgap, get the secret value from a teammate via Doppler instead.

10. Verification before calling it done ​

CLAUDE.md defines the mandatory verification gates that map 1:1 to CI Tier 1. Run the ones that match your change before you push:

Changed areaCommands
api/backend-ppp/cd api/backend-ppp && pnpm tsc && pnpm lint && pnpm lint:no-console
instances/ppp/cd instances/ppp && npx tsc --noEmit -p tsconfig-lint.json && pnpm lint && pnpm lint:no-console
packages-shared/ppp/pnpm tsc (from root)
Any of the abovenode .github/scripts/check-no-any.mjs (no-explicit-any gate)
Any backend test filescd api/backend-ppp && npx tsc --noEmit -p tsconfig.test.json

The full verification checklist — including BDD-first rule, no-any policy, and the migration + validator gate — lives in CLAUDE.md under Verify Before Done.


Contributions

Spot something wrong or out of date on this page? Edit docs/site/development/local-setup.md and open a PR against uat. Keep the cross-links pointing at the canonical sources — this page is a map, not a mirror.

Internal documentation — org members only