Environment Variables

Every setting is read from the environment, no config files, no vendor SDKs. The same surface applies whether you run Compose, a Helm chart, an ECS task definition, or a bare node process. Inject values from whatever secret store you already operate (Secrets Manager, Key Vault, Vault, sealed-secrets); the app doesn't care where they came from.

Nothing has a built-in default. Every variable marked required below must be set explicitly, in every environment. At startup the API server validates the whole configuration, collects every missing or invalid variable, prints one list naming each of them, and exits with status 78. The web server, the image build and the container entrypoint apply the same rule to the variables they read. Optional features are either off (variable unset) or fully configured; a half-configured feature, such as MAIL_TRANSPORT=smtp without SMTP_HOST, is a startup error rather than a silent downgrade. Blank values count as unset.

Invalid configuration (2 problems):
  - JWT_SECRET is not set (session token signing secret)
  - DB_POOL_MAX must be a whole number (got "twenty")
Refusing to start. Set the variables above and restart.

Required Secrets

openssl rand -hex 32   # 256-bit secret, hex-encoded

Server Runtime

Build-Time Variables

These are inlined into the browser bundle when the image or the web app is built, so they cannot be changed at run time. The build fails and names any that are missing.

Metadata Database

All application state, users, scripts, releases, connections, executions, approvals, audit, licenses, lives in one Postgres database. This is the application's own metadata store, distinct from the customer databases the IDE connects to. The migration runner needs CREATE TABLE on this database at first boot. Only the DB_DEVOPS_DB_* names are read.

Pool tuning

The metadata pool is pg (node-postgres). Raise DB_POOL_MAX only after confirming your Postgres max_connections headroom, or front the pool with PgBouncer in transaction mode.

Rate Limiting and Query Guards

The IP buckets back a 429 on breach. They count each client address: behind a reverse proxy, list the proxy in TRUST_PROXY (and have it send X-Forwarded-For), otherwise every request carries the proxy's address and collapses onto one bucket.

LLM Provider Endpoints

AI features (NL-to-SQL, risk audit, chat) select a provider, key, and model per tenant in Settings, those live in the metadata store. These variables set the API endpoint for each provider, which you can point at Azure OpenAI, an on-prem gateway or a compatible proxy, and the model used when a tenant has not chosen one. AWS Bedrock takes its region from the AI provider settings.

Email (optional)

Leave MAIL_TRANSPORT unset to run with no outbound email. Once it is set, the variables for that transport become required, and setting any mail variable without MAIL_TRANSPORT is a startup error. The same transport sends password-reset emails, issue reports and security alert emails.

The names SMTP_FROM, REPORT_SES_FROM and REPORT_SES_REGION are no longer read; startup reports them with their replacement.

Other Optional Integrations

Licensing

Keys are signed RSA-SHA256; the matching public key ships inside the image at LICENSE_PUBLIC_KEY_PATH, so verification is fully offline. Activate via the UI (Settings, License) or POST /api/license/activate. Every app container on the same database applies a license change at once: the database announces each change and every container reads the license again, so activating, replacing or removing a key on one container takes effect on all of them, however many run. Each container also reads the license again every 60 seconds, and before it refuses a request for want of a license.

Request Path

The browser never talks to Express directly for API calls. Every call traverses browser → Next.js API route (pages/api/*) → Express (:5002), the proxy layer forwards Authorization, X-Request-Id, and the bypass headers to BACKEND_URL. A new Express route is unreachable until its Next.js proxy exists. Live notifications and deployment status use Socket.IO at /socket.io on the same origin, which Next.js forwards to Express, so no extra port is needed. Health surface: GET /api/health (returns STARTING until the metadata DB is reachable) and GET /api/health/migrations (applied-migration inventory, consumed by deploy validators).

Blast Radius Tuning

Blast radius, the downstream-impact analysis surfaced before approval, walks the target's dependency graph via read-only catalog queries. These bounds keep the walk cheap on large or busy schemas.

Shadow Execution Tuning

Shadow execution dry-runs a migration against a disposable twin of the target. These bounds control where the twin lives and how a run is capped.

Reverse Proxy and CORS

The single most common misconfiguration is a CLIENT_URL that doesn't byte-match the browser origin, symptom is failed API calls (dashboard counts stuck at zero, "CORS policy" console errors). In production, front the container with a proxy (nginx/Traefik/Caddy or a cloud LB), terminate TLS there, route /api/* to :5002 and everything else (including /socket.io) to :3000, and serve UI and API same-origin to sidestep CORS entirely.

server {
    listen 443 ssl http2;
    server_name dbstudio.example.com;

    ssl_certificate     /etc/ssl/certs/dbstudio.crt;
    ssl_certificate_key /etc/ssl/private/dbstudio.key;

    location /api/ {
        proxy_pass http://localhost:5002;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

With that topology set CLIENT_URL=https://dbstudio.example.com and APP_PUBLIC_URL=https://dbstudio.example.com. Have the proxy send X-Forwarded-For and list its address or network in TRUST_PROXY (for Docker Compose, the compose network's range, e.g. 172.18.0.0/16), or audit entries record the proxy's address and rate limiting collapses onto a single bucket.

Real-time updates. Live notifications use Socket.IO at /socket.io on the UI port (3000), which forwards it to the API inside the container, so a proxy that sends everything else to :3000 needs no extra route. Allow WebSocket upgrades on that route, as in the Upgrade/Connection headers above. Without them the client falls back to HTTP long-polling, which still works. The connection is authenticated with the user's session and is refused without one.

Example .env

The shipped .env.example lists every variable with a working value. Copy it to .env, replace the secrets, set your URLs, then bring the stack up. The Compose file passes .env to the container and pins the values that describe the container itself (ports, file paths, BACKEND_URL, the metadata database host).

JWT_SECRET=replace_me_with_64_hex_chars
ENCRYPTION_KEY=replace_me_with_64_hex_chars
DB_DEVOPS_DB_NAME=db_devops
DB_DEVOPS_DB_USER=dbstudio
DB_DEVOPS_DB_PASSWORD=replace_me_with_strong_password
LOG_LEVEL=info
MIGRATE_ON_BOOT=true
CLIENT_URL=https://dbstudio.example.com
APP_PUBLIC_URL=https://dbstudio.example.com
# ...plus the pool, rate-limit, LLM, blast-radius and shadow settings
# from .env.example; the app lists any that are missing.