Environment Variables

Every knob is read from process.env at boot, 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.

Validation is fail-closed under NODE_ENV=production: the process exits non-zero at startup when any required secret is missing or below its minimum length. In development the same checks downgrade to a warning and continue, so local runs never block, and a misconfigured production deploy never boots silently degraded.

Required Secrets

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

Server Runtime

Metadata Database

All application state, users, scripts, releases, connections, executions, approvals, audit, licenses, lives in one Postgres database. This is Simcha'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.

Legacy DB_HOST / DB_PORT / DB_NAME / DB_USER / DB_PASSWORD are accepted as fallbacks for the DB_DEVOPS_* names.

Pool tuning

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

Rate Limiting

Two independent buckets, keyed per client IP, back a 429 on breach. Size them to your reverse-proxy trust boundary; if the proxy doesn't forward the real client IP, every request collapses onto one bucket.

LLM Provider Overrides

AI features (NL-to-SQL, risk audit, chat) select a provider, key, and model per tenant in Settings, those live in the metadata store, not in env. The env overrides below exist to retarget base URLs at Azure OpenAI, Bedrock, or on-prem gateways, and to pin model ids independent of tenant settings.

Security Alert Email (SMTP)

Security events route through the alert service. With no SMTP host configured, alerts stay in-app only. There is no literal fallback for the envelope sender, SMTP_FROM is mandatory once SMTP_HOST is set.

Tenant Branding

Support/sales contact links are tenant-owned. Left empty (the default), the corresponding UI affordances are simply not rendered, no Simcha addresses leak into a self-hosted deployment. The NEXT_PUBLIC_* pair is inlined into the client bundle at build time; the unprefixed pair is used in server-rendered messages.

Non-Prod Bypass Keys

Both headers inject a virtual admin and skip auth/RBAC entirely, they exist for test harnesses and internal automation. Both are hard-gated to NODE_ENV !== 'production': enabling them against a production build is a critical vulnerability, so guarantee your prod env actually sets NODE_ENV=production.

Licensing

Keys are signed RSA-SHA256; the matching public key ships inside the image, so verification is fully offline and no runtime license variable is required. Activate via the UI (Settings, License) or POST /api/license/activate. License state is cached in-process with a 60-second TTL, direct mutation of the license table won't take effect until the cache expires or an activate/deactivate call forces a refresh. LICENSE_SECRET is only consulted on builds using the legacy HMAC signing path; standard builds ignore it.

Request Path

The browser never talks to Express directly. Every call traverses browser → Next.js API route (pages/api/*) → Express (:5002), the proxy layer forwards Authorization, X-Request-Id, and the bypass headers, and pins the backend target via BACKEND_URL (default http://localhost:5002). A new Express route is unreachable until its Next.js proxy exists. 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 optional bounds keep the walk cheap on large or busy schemas; defaults suit most databases.

Shadow Execution Tuning

Shadow execution dry-runs a migration against a disposable twin of the target. These optional bounds control where the twin lives and how a run is capped; defaults need no infrastructure beyond the target connection.

Reverse Proxy and CORS

The single most common misconfiguration is a CLIENT_URL that doesn't byte-match the browser origin, symptom is silently 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 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_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 NEXT_PUBLIC_API_URL=https://dbstudio.example.com/api. Ensure the proxy forwards the real client IP or rate limiting collapses onto a single bucket.

Example .env

# --- REQUIRED ---
JWT_SECRET=replace_me_with_64_hex_chars
ENCRYPTION_KEY=replace_me_with_64_hex_chars
DB_PASSWORD=replace_me_with_strong_password

# --- METADATA DB ---
DB_USER=simcha
DB_NAME=db_devops

# --- RUNTIME ---
NODE_ENV=production
CLIENT_URL=https://dbstudio.example.com
NEXT_PUBLIC_API_URL=https://dbstudio.example.com/api
JWT_EXPIRES_IN=8h
MIGRATE_ON_BOOT=false

# Pin the image in production:
# SIMCHA_IMAGE=simchasolutions/db-studio:1.0.1

The shipped .env.example mirrors this template. Copy to .env, populate real secrets, then bring the stack up.