CMS Configuration Reference
Understand the environment settings needed for public URLs, storage, sessions, clustering, and installation.
Put deployment settings in .env at the application root, or inject them through your hosting platform. Settings supplied by the hosting environment take precedence over values read from .env. Restart the application after changing runtime configuration.
Use the environment example shipped with your release as a reference, but replace its localhost addresses and sample credentials.
Core deployment values
| Variable | Purpose and default |
|---|---|
DATABASE_URL | Required PostgreSQL connection string for the CMS |
NODE_ENV | Use production for a deployed installation; the bootstrap defaults to production |
HOST | Bind address; bootstrap default 0.0.0.0. Use 127.0.0.1 when only a local proxy needs access. |
PORT | Application listening port; default 3333 |
APP_URL | Canonical public origin, such as https://app.example.com. Set explicitly for production mail links, callbacks, and WebSocket origins. |
APP_KEY | Optional explicit application secret. The HTTP bootstrap adopts an existing key or persists a generated one in PostgreSQL. Retain the existing value across updates. |
APP_ROOT | Base for persistent storage paths; default ./, resolved from the working directory. An absolute path is easier to audit. |
SESSION_DRIVER | Use cookie, the configured durable session store and bootstrap default |
DRIVE_DISK | Use fs, the configured AdonisJS Drive disk |
TZ | Process timezone; default UTC |
LOG_LEVEL | Logging verbosity; bootstrap default info. Increase only as needed when investigating problems. |
APP_URL should be an origin without a page path. It is separate from the hostname presented during browser license activation. Configure both the public proxy and the environment correctly.
Storage and secrets
With APP_ROOT=/srv/brad-data, the local upload, backup, and log paths are:
/srv/brad-data/storage/uploads
/srv/brad-data/storage/backups
/srv/brad-data/storage/logsCreate persistent directories with ownership that allows the application user to write. Changing APP_ROOT changes where BRAD looks for files; it does not move existing uploads. Copy data deliberately and verify it before retiring the old storage.
The generated APP_KEY is stored in app_runtime_secret, a runtime table outside Prisma's managed schema. A complete database backup must retain it. An explicit key overrides a stored one, so unintentionally changing it can invalidate sessions and other protected data.
Real-time and clustering
| Variable | Use |
|---|---|
REDIS_URL | Redis connection URL for broadcasts between processes; required for independent process deployments and the production scaling path |
CLUSTER | Set true to enable the application's internal Node cluster |
CLUSTER_INSTANCES | Worker count, or max for one worker per CPU core |
DATABASE_POOL_MAX | Per-worker PostgreSQL pool limit; account for all workers when sizing database connections |
The built-in PM2 configuration uses fork mode to supervise the application's own cluster primary. If you use that configuration, retain its topology. See production hosting.
Integrations and HTTPS
Communication, payment, upload, and streaming providers are configured in the CMS Settings categories. Some providers also accept environment fallbacks, including SENDGRID_API_KEY and SENDGRID_FROM_EMAIL. Use the provider's own setup screen and tests rather than assuming an environment value alone activates it.
ENABLE_HSTS=true enables HSTS-related behavior where configured. Set it only after the real public hostname consistently serves HTTPS. Production sessions use secure cookies and need HTTPS.
Automated installation
INSTALL_AUTO, INSTALL_LICENSE_KEY, INSTALL_ADMIN_EMAIL, INSTALL_ADMIN_PASSWORD, INSTALL_ADMIN_NAME, INSTALL_COMPANY_NAME, and optional INSTALL_PUBLIC_URL control first-boot provisioning. See automated installation before using them.
Development-only gateway overrides
LICENSE_SERVER_URL can direct non-production CMS instances to a development license server. BRAD_CLOUD_URL similarly overrides the cloud gateway, otherwise development cloud calls can reuse the license server override.
Production ignores these URL overrides and uses the built-in BRAD production endpoint. Changing them is not a way to migrate a production installation to another issuer.