Environment variables

Backend variables

Validation is defined in backend/src/config/env.validation.ts using Zod. Missing or invalid variables fail startup with a descriptive error.

Required

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection string (pooled)	`postgresql://user:pass@host/db?connection_limit=10`
`DIRECT_URL`	Direct connection for migrations (used by Prisma, not validated by Zod)	`postgresql://user:pass@host/db`
`BETTER_AUTH_SECRET`	Session secret, minimum 32 characters	(32+ char random string)
`BETTER_AUTH_URL`	Backend base URL for auth	`https://api.muzemus.online`
`FRONTEND_ORIGIN`	Allowed CORS origin(s), comma-separated	`https://app.muzemus.online`

Optional

Variable	Default	Description
`NODE_ENV`	`development`	`development`, `test`, or `production`
`PORT`	`3001`	Server listen port
`BREVO_API_KEY` / `BREVO_SENDER_EMAIL`	— / `noreply@muze.co.za`	Production email via Brevo REST API (`xkeysib-...` key)
`SMTP_HOST` / `SMTP_PORT`	— / `587`	SMTP server for development email (e.g. Gmail)
`SMTP_USER` / `SMTP_PASS`	—	SMTP credentials
`SMTP_FROM_EMAIL`	`noreply@muze.co.za`	From address
`SMTP_FROM_NAME`	`Muze Uniform Solutions`	From name
`R2_ACCOUNT_ID` / `R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY`	—	Cloudflare R2 credentials
`R2_BUCKET_NAME` / `R2_PUBLIC_BASE_URL`	—	R2 bucket and public base URL
`FIREBASE_PROJECT_ID` / `FIREBASE_STORAGE_BUCKET`	—	Firebase Storage for product images
`FIREBASE_SERVICE_ACCOUNT_PATH` / `FIREBASE_ADMIN_KEY_PATH`	—	Firebase admin credentials

The email service prefers BREVO_API_KEY when set; otherwise it falls back to SMTP_HOST (nodemailer), and to console logging if neither is configured.

Frontend variables

Variable	Description	Example
`VITE_API_BASE_URL`	Backend API base URL (including `/api/v1`)	`https://api.muzemus.online/api/v1`
`VITE_AUTH_BASE_URL`	Better Auth base URL on the backend	`https://api.muzemus.online/api/auth`
`VITE_APP_URL`	Canonical production origin for the portal. Used for SEO metadata, canonical links, and the generated `robots.txt` and `sitemap.xml`. Change this one value when the site moves off the default Firebase host	`https://app.muzemus.online`

Only variables prefixed with VITE_ are exposed to the client bundle. VITE_APP_URL is defined in the committed frontend/.env.production and also documented in frontend/.env.example.

Environment file locations

backend/.env     # not committed to git
frontend/.env    # local overrides, not committed to git
frontend/.env.production  # committed: production build-time values (vite build)
frontend/.env.staging     # committed: staging build-time values (vite build --mode staging)

Use the .env.example files as templates.

Per-environment values

Variable	Production	Staging
`VITE_API_BASE_URL`	`https://api.muzemus.online/api/v1`	`https://stage-api.muzemus.online/api/v1`
`VITE_AUTH_BASE_URL`	`https://api.muzemus.online/api/auth`	`https://stage-api.muzemus.online/api/auth`
`VITE_APP_URL`	`https://app.muzemus.online`	`https://stage.muzemus.online`
`BETTER_AUTH_URL`	`https://api.muzemus.online`	`https://stage-api.muzemus.online`
`FRONTEND_ORIGIN`	`https://app.muzemus.online`	`https://stage.muzemus.online`

Security notes

Never commit .env files to version control
Use different secrets for development and production
Rotate BETTER_AUTH_SECRET periodically
Keep DATABASE_URL and DIRECT_URL confidential

Overview

System Architecture

Security

Business Engines

Notifications & Reports

Data

Operations

Engineering

Backend variables

Required

Optional

Frontend variables

Environment file locations

Per-environment values

Security notes

​Backend variables

​Required

​Optional

​Frontend variables

​Environment file locations

​Per-environment values

​Security notes

Backend variables

Required

Optional

Frontend variables

Environment file locations

Per-environment values

Security notes