Skip to content
Cadence AI Framework

Configuration

Environment variables, secrets, encryption, OAuth2, database, and production hygiene.

Intended audience: Stakeholders, Business analysts, Solution architects, Developers, Testers

Learning outcomes by role

Stakeholders

  • Recognize mandatory secrets and environment classes for production readiness.

Business analysts

  • Checklist configuration items for go-live sign-off.

Solution architects

  • Produce environment-specific matrices (dev, staging, prod) from this guide.

Developers

  • Set CADENCE_* variables and validate against AppSettings behavior.

Testers

  • Build config-focused smoke tests and misconfiguration detection.

Configure Cadence from environment variables prefixed CADENCE_ (secrets, Postgres URLs, Redis, RabbitMQ, CORS, OAuth, logging). The authoritative list is in the repository root .env.example. Immutable infrastructure settings load into AppSettings (cadence.core.config); operational defaults and feature flags that change at runtime live in the global_settings database table (not in env vars).

Summary for stakeholders

Section titled “Summary for stakeholders”
  • Secrets and compliance — CADENCE_SECRET_KEY, CADENCE_ENCRYPTION_KEY, and database URLs are deployment commitments; weak defaults are rejected or warned in production validation.
  • Separation — Env vars bootstrap the process; product operators tune many limits via admin APIs and global_settings, not by redeploying for every change.

Business analysis

Section titled “Business analysis”
  • Go-live checklist — Map each CADENCE_ variable in .env.example to an owner and verification step (smoke test, secret rotation procedure).
  • Non-functional requirements — CORS, OAuth redirect URLs, and log format tie directly to customer-facing browser apps and SIEM ingestion.

Architecture and integration

Section titled “Architecture and integration”
Environment variables to AppSettings Process environment variables with prefix CADENCE are loaded into AppSettings once at startup. Environment CADENCE_* vars .env optional AppSettings cadence.core.config Immutable infra: DB, Redis, secrets, CORS… FastAPI main

Runtime feature flags and tier defaults live in global_settings (DB), not AppSettings — see module docstring in cadence/core/config.py.

Prerequisites

Section titled “Prerequisites”
  • Infrastructure reachable: PostgreSQL, Redis, and optionally RabbitMQ
  • Secrets generated for production (openssl rand -hex 32 for the encryption key)

Environment variables

Section titled “Environment variables”

Security and tokens

Section titled “Security and tokens”
VariablePurpose
CADENCE_SECRET_KEYJWT signing secret — must be changed in production
CADENCE_ENCRYPTION_KEY64 hex chars (32 bytes AES-256) for encrypting secrets — generate with openssl rand -hex 32
CADENCE_JWT_ALGORITHMDefault HS256
CADENCE_ACCESS_TOKEN_TTL_SECONDSAccess token lifetime
CADENCE_REFRESH_TOKEN_TTL_SECONDSRefresh token lifetime

Infrastructure

Section titled “Infrastructure”
VariablePurpose
CADENCE_POSTGRES_URLPrimary PostgreSQL URL
CADENCE_POSTGRES_READ_URLOptional read replica (unset = use primary)
CADENCE_PGBOUNCER_ENABLEDtrue to use NullPool when PgBouncer fronts connections
CADENCE_REDIS_URLSession store, OAuth2 codes, rate limits
CADENCE_RABBITMQ_URLEvent bus for settings broadcast and pool lifecycle events

HTTP and CORS

Section titled “HTTP and CORS”
VariablePurpose
CADENCE_CORS_ORIGINSComma-separated allowed browser origins

OAuth2 and social login

Section titled “OAuth2 and social login”
VariablePurpose
CADENCE_OAUTH_REDIRECT_BASE_URLNuxt app base URL for OAuth callback (default http://localhost:3000)
CADENCE_CONSENT_UI_URLFull URL to consent page (default {oauth_redirect_base_url}/oauth/consent)
CADENCE_GOOGLE_CLIENT_ID / _SECRETGoogle social OAuth
CADENCE_GITHUB_CLIENT_ID / _SECRETGitHub social OAuth
CADENCE_OAUTH2_CLIENT_ID / _SECRET / _AUTHORIZATION_URL / _TOKEN_URL / _USERINFO_URLGeneric OAuth2 provider for social login
CADENCE_OAUTH2_SCOPESDefault openid email profile

Runtime behavior

Section titled “Runtime behavior”
VariablePurpose
CADENCE_LOG_FORMATjson or text
CADENCE_ENVIRONMENTdevelopment / production / etc.

Initial setup

Section titled “Initial setup”
  1. Copy .env.example to .env.
  2. Bring up infrastructure (Docker Compose or your platform): PostgreSQL, Redis, RabbitMQ.
  3. Run migrations and bootstrap the admin user.
  4. Set CADENCE_CORS_ORIGINS to your UI origin.
  5. Start the API and UI; verify health endpoints (Monitoring).

Verification and quality

Section titled “Verification and quality”

Troubleshooting

Section titled “Troubleshooting”
SymptomCauseFix
500 on startupDatabase URL, credentials, or networkCheck CADENCE_POSTGRES_URL and connectivity
Sessions flaky or droppedRedis unavailableCheck CADENCE_REDIS_URL and Redis health
No JSON logsCADENCE_LOG_FORMAT not setSet CADENCE_LOG_FORMAT=json
encryption_key validation errorNot exactly 64 hex charactersRegenerate with openssl rand -hex 32

Next steps

Section titled “Next steps”
Monitoring Health endpoints, pool stats, and log shipping.
Observability OpenTelemetry configuration and structured log usage.