Configuration

Summary

RedCloud is configured through environment variables (a .env file in Compose, or a Secret in Kubernetes). In production the platform enforces a fail-fast policy: if a required secret is missing or an insecure setting is detected, the backend refuses to start. This page lists the variables and the exact conditions that block a boot.

Danger

Never commit .env or credential files. Generate strong secrets and store them in your secret manager. Default and weak secrets are rejected at startup in production.

Core / server

Variable	Purpose	Required	Default
ENVIRONMENT	production or development	No	production
PORT	Backend port (Cloud Run injects its own)	No	9900
LICENSE_PORT	License server port	No	7700
DATABASE_URL	PostgreSQL DSN	Yes (prod)	local dev DSN
DB_PASSWORD	Compose database password	Yes (Compose)	—
TIMEZONE	Scheduler timezone	No	Asia/Jerusalem

Security (required in production)

Variable	Purpose	Blocks boot if…
HMAC_KEY	Signs JWTs / tokens	unset in production
API_KEY	Global API authentication	unset in production
ENCRYPTION_KEY	Encrypts config / data at rest	unset in production (no silent fallback)
STORAGE_MODE	strict / migration / compat	set to compat/unknown in production
FRONTEND_ORIGINS	CORS allowlist (CSV)	(warning only; falls back to dev origins if unset)
RATE_LIMIT	Global API rate limit	— (default 60/minute)

Generate secrets:

# HMAC_KEY / API_KEY / ENCRYPTION_KEY
python -c "import secrets; print(secrets.token_hex(32))"

Break-glass (governed, off by default)

Variable	Purpose	Default
BREAK_GLASS_ENABLED	Enables break-glass access	false
MASTER_KEY / MASTER_KEY_FILE	The break-glass key (python -m api.master_key)	—
BREAK_GLASS_TTL	Session TTL in seconds	1800

If BREAK_GLASS_ENABLED=true without a MASTER_KEY, the boot is blocked. Break-glass grants a scoped permission set, is rate-limited and fully audited, and never bypasses tenant isolation.

Licensing

Variable	Purpose
LICENSE_KEY	Customer key (RC-...)
LICENSE_SERVER_URL	Must be HTTPS in production
REDCLOUD_LICENSE_SECRET	Shared secret; must match the license server (missing logs a critical warning)

Authentication & SSO (optional)

Google OAuth (GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET), SAML, 2FA (TOTP_ISSUER), and Google Cloud IAP:

Variable	Default
IAP_AUTH_ENABLED	false
IAP_EXPECTED_AUDIENCE	— (/projects/<num>/global/backendServices/<id>)
IAP_ALLOWED_DOMAINS	— (CSV, optional)
IAP_AUTO_PROVISION_ENABLED	false

AI providers (optional)

AI_PROVIDER (one of anthropic, openai, gemini, vertex, xai, mistral, deepseek, ollama), AI_API_KEY, AI_MODEL, multi-provider AI_PROVIDERS (JSON), AI_FALLBACK_ORDER, and AI_BUDGET_MAX_USD. Vertex AI uses VERTEX_ENABLED, VERTEX_PROJECT_ID, VERTEX_REGION, and Workload Identity.

The fail-fast startup security policy

In production, any of the following blocks startup (the backend raises and exits):

1. HMAC_KEY not set.
2. API_KEY not set.
3. ENCRYPTION_KEY not set (no silent fallback).
4. REDCLOUD_DEV_MODE=true.
5. STORAGE_MODE is compat or unknown (must be strict or migration).
6. BREAK_GLASS_ENABLED=true without a MASTER_KEY.
7. Any tenant-bypass flag is true (BYPASS_TENANT_CHECKS, TENANT_ISOLATION_DISABLED, TENANT_MIGRATION_MODE, DISABLE_TENANT_CHECK, DISABLE_TENANT_ISOLATION).
8. A critical secret-validation issue (e.g. a weak/short key or a default DB_PASSWORD).
9. The database is unreachable (a SELECT 1 probe runs before the gate).

Caution

There is an explicit, audited emergency override (SECURITY_PERMIT_INSECURE_BOOT=true) that boots in an unsafe mode. Use it only in a genuine emergency — it is recorded in the audit log.

Notes

• Dev mode requires both ENVIRONMENT=development and REDCLOUD_DEV_MODE=true; it can never be enabled in production.
• Database tables are created idempotently at startup; there is no separate migration step for the core schema.

Next steps

• Docker Deployment · Kubernetes Deployment
• Troubleshooting
• Security & Compliance