Environment Variables Complete reference for all environment variables.
Raypx uses environment variables for all external configuration. Values are validated at startup by @raypx/env using Zod schemas. Copy .env.example to .env and fill in your values.
Variables prefixed with VITE_PUBLIC_ are exposed to the browser bundle by Vite. These are accessible via import.meta.env.VITE_PUBLIC_* on the client. All other variables are server-only and never sent to the browser.
Never store secrets in VITE_PUBLIC_ variables. They are embedded in the JavaScript bundle and visible to anyone who inspects network traffic.
Variable Required Default Description APP_KEYYes — Random string for application-level encryption. Generate with openssl rand -base64 48. VITE_PUBLIC_WEB_URLYes http://localhost:3000Public URL of the application, used in emails and OAuth redirects. VITE_PUBLIC_PROJECT_NAMENo RaypxDisplay name shown in the UI. VITE_PUBLIC_BASE_URLYes http://localhost:3000Base URL for API calls from the browser.
Variable Required Default Description DATABASE_URLYes — PostgreSQL connection string. Format: postgres://user:password@host:5432/dbname. DATABASE_POOL_MAXNo 10Maximum number of connections in the pool. DATABASE_IDLE_TIMEOUTNo 20Seconds before an idle connection is released.
Variable Required Default Description AUTH_SECRETYes — Better Auth secret. Must be at least 32 characters. Generate with openssl rand -base64 48. AUTH_URLNo VITE_PUBLIC_BASE_URLServer-side auth callback URL. Defaults to the base URL. ADMIN_EMAILSNo — Comma-separated list of admin email addresses.
Variable Required Default Description VITE_PUBLIC_AUTH_GOOGLE_IDNo — Google OAuth client ID (public). AUTH_GOOGLE_SECRETYes (if Google enabled) — Google OAuth client secret (server-only). VITE_PUBLIC_AUTH_GOOGLE_ENABLEDNo trueEnable or disable Google sign-in. VITE_PUBLIC_AUTH_GOOGLE_ONE_TAP_ENABLEDNo falseEnable Google One Tap sign-in.
Variable Required Default Description AUTH_GITHUB_IDNo — GitHub OAuth application ID (server-only). AUTH_GITHUB_SECRETNo — GitHub OAuth application secret (server-only). VITE_PUBLIC_AUTH_GITHUB_ENABLEDNo trueEnable or disable GitHub sign-in.
Variable Required Default Description AUTH_RESEND_KEYNo — Resend API key for sending transactional emails. RESEND_FROMNo — Sender email address, e.g. noreply@yourdomain.com. MAIL_HOSTNo — Custom SMTP host (overrides Resend). MAIL_PORTNo — Custom SMTP port. MAIL_USERNo — Custom SMTP username. MAIL_PASSWORDNo — Custom SMTP password. MAIL_SECURENo — Use TLS for custom SMTP (true/false).
Variable Required Default Description STORAGE_DRIVERNo localStorage driver: local or s3. STORAGE_LOCAL_ROOTNo .storageRoot directory for local file storage. STORAGE_REDIS_URLNo — Redis URL for signed URL storage. STORAGE_REDIS_BASENo — Redis key prefix for storage entries. STORAGE_REDIS_TTL_SECONDSNo — TTL for Redis storage entries. REDIS_URLNo — General-purpose Redis connection string.
Variable Required Default Description VITE_PUBLIC_DEFAULT_THEMENo darkDefault color theme: light, dark, or system. VITE_PUBLIC_LOCALE_DETECTIONNo falseEnable automatic locale detection from browser headers. VITE_PUBLIC_AUTH_URLNo VITE_PUBLIC_BASE_URLClient-side auth URL for redirects.
All AI provider keys are optional. Set only the ones you plan to use.
Variable Required Default Description OPENAI_API_KEYNo — OpenAI API key. OPENAI_PROXY_URLNo — Custom proxy URL for OpenAI requests. DEEPSEEK_API_KEYNo — DeepSeek API key. DEEPSEEK_PROXY_URLNo — Custom proxy URL for DeepSeek requests. ZHIPU_API_KEYNo — Zhipu AI (ChatGLM) API key.
Variable Required Default Description VITE_PUBLIC_GOOGLE_ANALYTICS_IDNo — Google Analytics measurement ID (e.g. G-XXXXXXXXXX).
All environment variables are validated on server startup by @raypx/env. If a required variable is missing or has an invalid format, the server logs a detailed error and exits. Check the console output after starting the server to catch configuration issues early.