Backend PPP Environment Variables
This document lists the environment variables used by the PPP backend and related shared services.
Core Runtime
DATABASE_URL- Required. PostgreSQL connection string.
TEST_DATABASE_URL- Required when
NODE_ENV=test. PPP DB access uses this value for test runs. - Get the value from Doppler (
ppp/share → TEST_DATABASE_URL) or ask the team. - In CI this is overridden by a local postgres instance spun up by GitHub Actions.
- Required when
AWS_REGION- Required for AWS SDK clients (storage, etc.).
STORAGE_KEY_PREFIX- Optional. Prefix applied to all storage keys (e.g.,
test/ppp-dev).
- Optional. Prefix applied to all storage keys (e.g.,
AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY- Optional for local dev if not using instance role.
File Storage
STORAGE_KEY_PREFIX
Used by storage helpers and presigned upload URL generation. Public keys are stored under public/<prefix>/....
AI / OCR
GEMINI_API_KEY- Required for OCR image analysis (Gemini).
Payments
STRIPE_SECRET_KEY- Required for server-side Stripe operations.
- Prefix must match
NODE_ENV(#4973):NODE_ENV=productionrequires a live key (sk_live_orrk_live_); any otherNODE_ENVrequires a test key (sk_test_orrk_test_). - A mismatch is detected at startup by
assertStripeKeyForEnvironment()insrc/services/paymentService/validateStripeKey.ts— the process throws beforeapp.listen()so the container fails readiness instead of silently accepting (or no-opping) real payments.
STRIPE_PUBLISHABLE_KEY- Required for frontend configuration via
getStripeConfig.
- Required for frontend configuration via
Notifications & Integrations
WEB_APP_BASE_URL- Required. Full web app URL used to build approval/review links in emails (for example,
https://pppdev.example.com).
- Required. Full web app URL used to build approval/review links in emails (for example,
EMAIL_ASSET_BASE_URL- Required. HTTPS base URL for branded email assets (logo PNGs) hosted on Cloudflare Pages.
- Example:
https://app.professionalperformanceportfolio.com/email-assets - The branded email shell (
renderBrandedEmail) throws at startup if unset. - Assets live in
instances/ppp/public/email-assets/and are deployed with every Cloudflare Pages build. - Added in #4943 (epic #4942).
AZURE_COMMUNICATION_CONNECTION_STRING- Required for email delivery via Azure Communication Services (signup credentials, CPD approvals, timesheet approvals).
- Secret lineage: Doppler (
ppp/uatorppp/prod) →requireEnvSecretin Pulumi → injected directly into Container App env var. - Expected format:
endpoint=https://<resource>.communication.azure.com/;accesskey=<key>. - Sender address:
noreply@professionalperformanceportfolio.com(must be configured as a verified sender domain in the Azure Communication Services resource). - To diagnose delivery failures:
ContainerAppConsoleLogs_CL | where Log_s contains "mailer" or Log_s contains "signup email"
GOOGLE_MAP_API_KEY- Required for Google Maps address search.
XERO_CLIENT_IDXERO_CLIENT_SECRET- Required for Xero integration.
Token Signing Secrets
These three variables are required — the app will throw at startup if any is absent.
CPD_APPROVAL_SECRET- HMAC-SHA256 key for signing CPD activity approval email tokens (default TTL: 30 days).
SECRET_360_KEY- HMAC-SHA256 key for signing 360-degree peer review invitation tokens (default TTL: 30 days).
TIMESHEET_BATCH_SECRET- HMAC-SHA256 key for signing timesheet batch approval tokens (default TTL: 7 days).
These are not credentials for any external service. Any cryptographically random string is valid for local development. Run the setup script to auto-generate them:
bash
bash api/backend-ppp/scripts/setup-local-env.shIn production/UAT/staging these are injected by Doppler (ppp/share config).
Optional TTL overrides (values in days):
CPD_APPROVAL_TOKEN_TTL_DAYS— overrides the 30-day default for CPD approval tokensTIMESHEET_BATCH_TOKEN_TTL_DAYS— overrides the 7-day default for timesheet batch tokensREVIEW_360_TOKEN_TTL_DAYS— overrides the 30-day default for 360 review tokens
Auth (optional)
BETTER_AUTH_BASE_URL- Optional but recommended to avoid warnings in local tests.
BETTER_AUTH_COOKIE_DOMAIN- Set in UAT/prod to
.professionalperformanceportfolio.comso session cookies are shared across subdomains (frontend and API). Leave unset for local dev.
- Set in UAT/prod to