Configuration

All environment variables and Docker images for self-hosted BuildBase.

Environment Variables

Installation (Required)

These are provided by the BuildBase dashboard when you create an Installation.

Variable	Description
`INSTALLATION_API_KEY`	Installation API key (from dashboard)
`INSTALLATION_ID`	Installation ID (from dashboard)

Server (Required)

Variable	Description
`NODE_ENV`	Set to `production`
`PORT`	Server port (default: `3000`)
`MONGO_CONNECTION_URL`	MongoDB connection string
`REDIS_HOST`	Redis hostname (default: `localhost`)
`REDIS_PORT`	Redis port (default: `6379`)
`SERVER_URL`	Public URL of the tenant server (default: `http://localhost:4101`)
`APPLICATION_URL`	Public URL of the client app (default: `http://localhost:4100`)
`AUTH_SERVER_URL`	Public URL of the auth portal (default: `http://localhost:4103`)
`JWT_PASS`	JWT signing secret
`DB_ENCRYPTION_KEY`	Database field encryption key
`SECRET_KEY`	General application secret
`OAUTH2_SECRET`	OAuth2 token secret
`INSTALLATION_API_KEY`	Installation API key (from BuildBase dashboard)
`INSTALLATION_ID`	Installation ID (from BuildBase dashboard)

Client App

Variable	Description
`NEXT_PUBLIC_SERVER_URL`	Tenant server URL
`NEXT_PUBLIC_DEFAULT_TENANT_SERVER_URL`	Default tenant server URL
`NEXT_PUBLIC_INSTALLATION_ID`	Installation ID (for org filtering)

CORS

Variable	Description
`CORS_WHITELISTED_DOMAINS`	Comma-separated list of allowed origins

The platform origins (console.buildbase.app) are always allowed by default.

Redis

Variable	Description	Default
`REDIS_PASSWORD`	Password (if required)	—
`REDIS_DB`	Database number	`0`

Optional Services

Variable	Description
`TRUST_PROXY`	How many proxies sit in front of the server and append to X-Forwarded-For. Defaults to 0 for self-hosted, which is right when the compose file publishes the port directly. Set it to the number of appending proxies if you put nginx, a load balancer or Cloudflare in front - too high and every per-IP rate limit is bypassable by a header the caller writes.
`GOOGLE_AUTH_CLIENT_ID`	Google OAuth client ID (for Google vendor + Gmail sender)
`GOOGLE_AUTH_CLIENT_SECRET`	Google OAuth client secret
`GOOGLE_STORAGE_ASSETS_BUCKET_NAME`	GCS bucket for file uploads
`GOOGLE_WEB_RISK_API_KEY`	Google Web Risk API key for checking redirect destinations. Unset disables reputation checks; links still work.
`MAIL_TRACKING_SECRET`	Signing key for email open/click tracking links. Derived from JWT_PASS when unset; set it to make the tracking key fully independent of the auth key.
`URL_SAFETY_LOG_ONLY`	Record URL reputation verdicts without acting on them. Defaults to false, so setting GOOGLE_WEB_RISK_API_KEY starts refusing malicious destinations straight away. Set this to true first to measure the false-positive rate before enforcing. (default: `false`)
`URL_SAFETY_ENABLED`	Master switch for URL reputation checks. Only the literal "false" turns them off, and every lookup then returns UNKNOWN. (default: `true`)
`URL_SAFETY_CLEAN_TTL_SECONDS`	How long a clean verdict may be cached, in seconds, capped at 86400. A threat verdict ignores this and honours the expiry Google returns. (default: `3600`)
`WEB_RISK_TIMEOUT_MS`	Timeout for a single Web Risk lookup, in milliseconds. Lookups sit on a background path but must not hang a worker. (default: `5000`)
`MAILGUN_API_KEY`	Mailgun API key (for transactional emails)
`NEW_RELIC_LICENSE_KEY`	New Relic ingest license key for YOUR OWN account. Unset (default) disables all APM/log telemetry - nothing is collected or sent
`NEW_RELIC_APP_NAME`	APM application name shown in New Relic (defaults to buildbase-server-selfhost)
`NEW_RELIC_BROWSER_ACCOUNT_ID`	New Relic account ID for browser monitoring of the client and auth frontends (shared across apps). Unset (default) disables browser monitoring
`NEW_RELIC_BROWSER_LICENSE_KEY`	New Relic browser license key (NRJS-…, shared across apps) for YOUR OWN account
`NEW_RELIC_BROWSER_APP_ID_CLIENT`	New Relic browser application ID for the client (console) frontend
`NEW_RELIC_BROWSER_APP_ID_AUTH`	New Relic browser application ID for the auth frontend

Generating Secrets

All secret values should be unique, random strings. Generate them with:

openssl rand -hex 32

Or generate all required secrets at once:

for i in JWT_PASS DB_ENCRYPTION_KEY SECRET_KEY OAUTH2_SECRET REDIS_PASSWORD; do echo "$i=$(openssl rand -hex 32)"; done

Docker Images

Image	Description	Port	Health Check
`buildbaseapp/tenant-server`	Backend API server	3000	`GET /api/ready`
`buildbaseapp/client`	Web dashboard (Next.js SSR)	3000	`GET /`
`buildbaseapp/auth`	Auth portal (Next.js)	3000	`GET /health`

All images are multi-arch (linux/amd64, linux/arm64), built on Node.js 22 Alpine. docker pull selects the correct variant for the host automatically. 32-bit ARM (linux/arm/v7) is not supported - see Supported architectures.

Architecture

Loading diagram...

Your data never leaves your infrastructure. The central server only handles authentication tokens, installation licensing, and organization metadata.