Getting Started
Environment Variables Complete reference for every environment variable used across Prood applications.
Prood uses a single root .env.local file for local development. Run pnpm env:link to generate ignored apps/*/.env.local files with app-specific auth URL overrides.
Variable Required Used by Description DATABASE_URLYes All apps Neon Postgres connection string. Shared by commerce data (@prood/platform) and Better Auth tables.
DATABASE_URL = "postgresql://user:password@host/db?sslmode=require" Variable Required Used by Description DEFAULT_TENANT_ORG_IDDev Storefront, API Fallback org when host-based tenant resolution fails. Set to seeded org id after pnpm db:setup. Unset in production → unmatched hosts return 404. NEXT_PUBLIC_PLATFORM_DOMAINProd Storefront, Dashboard, API Apex for merchant storefront subdomains only ({slug}.prood.app). Platform services run on prood.com. Example: prood.app.
Variable Default Description COMMERCE_CURRENCYEURDefault store currency (ISO 4217).
Variable Default Description STORAGE_PROVIDERvercel-blobvercel-blob or s3BLOB_READ_WRITE_TOKEN— Vercel Blob token (when STORAGE_PROVIDER=vercel-blob) S3_ENDPOINT— S3-compatible endpoint (R2, AWS, MinIO) S3_REGIONautoS3 region S3_BUCKET— Bucket name S3_ACCESS_KEY_ID— Access key S3_SECRET_ACCESS_KEY— Secret key S3_PUBLIC_URL— Public CDN URL for uploaded assets
Uploaded files are namespaced per tenant: org/<orgId>/… via uploadForTenant().
Variable Required Used by Description BETTER_AUTH_SECRETYes (prod) API, dashboard (SSR), storefront Session signing secret. Generate: openssl rand -base64 32 BETTER_AUTH_URLYes API (and storefront)Public origin of the Better Auth HTTP handler. API: http://localhost:3005. Storefront: http://localhost:3000. Dashboard does not host /api/auth. NEXT_PUBLIC_AUTH_URLYes Dashboard (browser) Origin the dashboard auth client calls for sign-in/sign-up/org ops. Same as API: http://localhost:3005 NEXT_PUBLIC_DASHBOARD_URLProd API (trustedOrigins) Merchant admin URL, e.g. https://dashboard.prood.com. On Vercel preview deploys, set this on the API project to your dashboard URL (e.g. https://dashboard-prood.vercel.app). AUTH_COOKIE_DOMAINProd API Shared cookie domain for dashboard + API on *.prood.com, e.g. .prood.com. Unset locally and on *.vercel.app preview URLs (browsers cannot share cookies across separate *.vercel.app hostnames).
Variable Description ADMIN_EMAILInitial platform admin email (used during db:migrate seed) ADMIN_PASSWORDInitial platform admin password
Variable Default Description DEFAULT_PAYMENT_PROVIDERstripeDefault gateway: stripe, easypay, or ifthenpay
Variable Description STRIPE_SECRET_KEYServer-side Stripe secret key STRIPE_WEBHOOK_SECRETWebhook signing secret NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEYClient-side publishable key (checkout app)
Variable Description EASYPAY_ACCOUNT_IDEasypay account ID EASYPAY_API_KEYAPI key EASYPAY_BASE_URLhttps://api.prod.easypay.pt (prod) or https://api.test.easypay.pt (sandbox)
Variable Description IFTHENPAY_ANTIPHISHING_KEYAnti-phishing verification key IFTHENPAY_MB_KEYMultibanco key IFTHENPAY_MBWAY_KEYMB WAY key IFTHENPAY_CC_KEYCredit card key
Per-tenant credentials configured in the dashboard override these env fallbacks. See Payment integration .
Variable Required Description CHECKOUT_URLYes Public URL of apps/checkout. Storefront redirects here after order placement. Default: http://localhost:3004 CHECKOUT_API_SECRETYes Shared secret between storefront and checkout. Sent as x-checkout-secret header. Generate: openssl rand -base64 32 COMMERCE_API_URLYes API base for webhook forwarding. Default: http://localhost:3005/v1
Variable Required Used by Description UPSTASH_REDIS_REST_URLCheckout apps/checkoutRedis REST endpoint for session storage UPSTASH_REDIS_REST_TOKENCheckout apps/checkoutRedis REST token
Checkout sessions (@prood/checkout-host) are persisted in Redis with a configurable TTL. Without Redis, the checkout app cannot create or load sessions.
Optional for local dev; required for custom domain provisioning in production:
Variable Description VERCEL_TOKENVercel API token STOREFRONT_VERCEL_PROJECT_IDStorefront Vercel project ID. Do not use Vercel's injected VERCEL_PROJECT_ID; it points at the current project, not necessarily the storefront. VERCEL_TEAM_IDVercel team ID (if applicable)
Variable Default Description COMMERCE_API_URLhttp://localhost:3005/v1Base URL for @prood/api-client in storefront and dashboard API_PUBLIC_URLhttp://localhost:3005Public API origin for Agent Auth OpenAPI proxy and discovery AGENT_PROXY_API_KEY— API key sent on proxied agent requests; metadata must include organizationId and scopes AGENT_DEVICE_AUTH_PAGE/device/capabilitiesMerchant approval UI path for device authorization TRUST_PROXYfalseSet true behind a reverse proxy for JWT aud validation
Variable Description INTEGRATION_ENCRYPTION_KEYYes
Variable Description NEXT_PUBLIC_DOCS_URLDocs site URL (default http://localhost:3003) NEXT_PUBLIC_STOREFRONT_URLStorefront URL for marketing CTAs
App Critical vars storefront DATABASE_URL, COMMERCE_API_URL, BETTER_AUTH_SECRET, BETTER_AUTH_URL, CHECKOUT_URL, CHECKOUT_API_SECRET, DEFAULT_TENANT_ORG_IDdashboard DATABASE_URL, COMMERCE_API_URL, BETTER_AUTH_SECRET, NEXT_PUBLIC_AUTH_URL, INTEGRATION_ENCRYPTION_KEYcheckout UPSTASH_REDIS_*, CHECKOUT_API_SECRET, COMMERCE_API_URL, payment provider keysapi DATABASE_URL, BETTER_AUTH_*, AUTH_COOKIE_DOMAIN, COMMERCE_CURRENCY, payment/storage provider keys, CHECKOUT_API_SECRET, RESEND_*admin DATABASE_URL, BETTER_AUTH_SECRET, NEXT_PUBLIC_ADMIN_URL, ADMIN_USER_IDSdocs None (static site; OpenAPI synced at build time)
Generate strong secrets: BETTER_AUTH_SECRET, CHECKOUT_API_SECRET, INTEGRATION_ENCRYPTION_KEY
Set DEFAULT_TENANT_ORG_ID only for single-tenant deployments; otherwise rely on host resolution
Configure NEXT_PUBLIC_PLATFORM_DOMAIN for subdomain tenants
Provision Upstash Redis for checkout
Set RESEND_API_KEY and a verified-domain RESEND_FROM_EMAIL
Set production payment keys (or configure per-tenant in dashboard)
Point webhook URLs to checkout: /api/webhooks/{stripe\|easypay\|ifthenpay}/{orgId}
Run pnpm db:setup against the production database once