> ## Documentation Index
> Fetch the complete documentation index at: https://system.muzemus.online/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment variables

> Reference for all environment variables across backend and frontend

## 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