Skip to content

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.
  • AWS_REGION
    • Required for AWS SDK clients (storage, etc.).
  • STORAGE_KEY_PREFIX
    • Optional. Prefix applied to all storage keys (e.g., test/ppp-dev).
  • 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=production requires a live key (sk_live_ or rk_live_); any other NODE_ENV requires a test key (sk_test_ or rk_test_).
    • A mismatch is detected at startup by assertStripeKeyForEnvironment() in src/services/paymentService/validateStripeKey.ts — the process throws before app.listen() so the container fails readiness instead of silently accepting (or no-opping) real payments.
  • STRIPE_PUBLISHABLE_KEY
    • Required for frontend configuration via getStripeConfig.

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).
  • 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/uat or ppp/prod) → requireEnvSecret in 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_ID
  • XERO_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.sh

In 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 tokens
  • TIMESHEET_BATCH_TOKEN_TTL_DAYS — overrides the 7-day default for timesheet batch tokens
  • REVIEW_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.com so session cookies are shared across subdomains (frontend and API). Leave unset for local dev.

Internal documentation — org members only