Skip to main content

​
Environment Variables

CHAD is configured via environment variables. This page documents all available options.

​
Required Variables

These must be set for production deployments:

​
Security Secrets

VariableDescriptionExample
JWT_SECRET_KEYJWT signing key (32+ chars)openssl rand -base64 32
SESSION_SECRET_KEYSession middleware key (32+ chars)openssl rand -base64 32
CHAD_ENCRYPTION_KEYCredential encryption key (32+ chars)openssl rand -base64 32
Never use default or weak secrets in production. Generate unique cryptographically random values.

​
Database

VariableDescriptionDefault
POSTGRES_HOSTPostgreSQL hostnamepostgres
POSTGRES_PORTPostgreSQL port5432
POSTGRES_USERPostgreSQL usernamechad
POSTGRES_PASSWORDPostgreSQL passwordRequired
POSTGRES_DBPostgreSQL database namechad

​
Application

VariableDescriptionDefault
APP_URLPublic URL for CHADRequired for CSRF

​
Optional Variables

​
Logging

VariableDescriptionDefault
LOG_LEVELLogging levelwarning
Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
Use WARNING or higher in production. DEBUG can expose sensitive data in logs.

​
Security

VariableDescriptionDefault
ALLOWED_HOSTSComma-separated allowed hostnames*
DEBUGEnable debug modefalse
CHAD_SSO_ONLYDisable local loginfalse

​
JWT Configuration

VariableDescriptionDefault
JWT_ALGORITHMJWT signing algorithmHS256
JWT_ACCESS_TOKEN_EXPIRE_HOURSToken expiration8

​
Database Tuning

VariableDescriptionDefault
DATABASE_POOL_SIZEConnection pool size5
DATABASE_MAX_OVERFLOWMax overflow connections10
DATABASE_POOL_TIMEOUTPool timeout seconds30

​
Backend Server

VariableDescriptionDefault
BACKEND_HOSTBind host0.0.0.0
BACKEND_PORTBind port8000
BACKEND_WORKERSUvicorn workers1

​
Frontend

VariableDescriptionDefault
VITE_API_URLBackend API URL/api

​
Example Configurations

​
Development

# .env
POSTGRES_PASSWORD=devpassword
JWT_SECRET_KEY=dev-only-not-for-production-12345
SESSION_SECRET_KEY=dev-only-not-for-production-12345
CHAD_ENCRYPTION_KEY=dev-only-not-for-production-12345
APP_URL=http://localhost:3000
LOG_LEVEL=debug
DEBUG=true

​
Production

# .env
POSTGRES_HOST=postgres.internal
POSTGRES_PASSWORD=<secure-generated-password>
POSTGRES_DB=chad

JWT_SECRET_KEY=<32-char-random-string>
SESSION_SECRET_KEY=<32-char-random-string>
CHAD_ENCRYPTION_KEY=<32-char-random-string>

APP_URL=https://chad.example.com
ALLOWED_HOSTS=chad.example.com

LOG_LEVEL=warning
DEBUG=false

DATABASE_POOL_SIZE=10
DATABASE_MAX_OVERFLOW=20

​
High Availability

# .env
POSTGRES_HOST=postgres-primary.internal
POSTGRES_PASSWORD=<secure-password>

JWT_SECRET_KEY=<shared-across-instances>
SESSION_SECRET_KEY=<shared-across-instances>
CHAD_ENCRYPTION_KEY=<shared-across-instances>

APP_URL=https://chad.example.com
ALLOWED_HOSTS=chad.example.com

BACKEND_WORKERS=4
DATABASE_POOL_SIZE=20
DATABASE_MAX_OVERFLOW=40

​
Generating Secrets

​
Using OpenSSL

# Generate 32-byte base64 secret
openssl rand -base64 32

​
Using Python

import secrets
print(secrets.token_urlsafe(32))

​
Using /dev/urandom

head -c 32 /dev/urandom | base64

​
Secrets Management

​
Environment Files

For Docker Compose, use .env file: 
# Never commit .env to version control!
echo ".env" >> .gitignore

​
Docker Secrets

For Docker Swarm: 
# docker-compose.yml
secrets:
  jwt_secret:
    external: true

services:
  backend:
    secrets:
      - jwt_secret
    environment:
      JWT_SECRET_KEY_FILE: /run/secrets/jwt_secret

​
Kubernetes Secrets

apiVersion: v1
kind: Secret
metadata:
  name: chad-secrets
type: Opaque
stringData:
  jwt-secret: "<your-secret>"
  session-secret: "<your-secret>"
  encryption-key: "<your-secret>"

​
Vault Integration

For HashiCorp Vault: 
# Store secrets
vault kv put secret/chad \
  jwt_secret="<value>" \
  session_secret="<value>" \
  encryption_key="<value>"

# Retrieve in app
export JWT_SECRET_KEY=$(vault kv get -field=jwt_secret secret/chad)

​
Validation

CHAD validates configuration on startup:

​
Required Check

Missing required variables cause startup failure: 
ERROR: JWT_SECRET_KEY is required

​
Security Check

Insecure defaults in production cause failure: 
ERROR: JWT_SECRET_KEY appears to be a default/weak value

​
Format Check

Invalid formats are reported: 
ERROR: LOG_LEVEL must be one of: DEBUG, INFO, WARNING, ERROR, CRITICAL

​
Troubleshooting

​
”Secret key is insecure”

  1. Generate a proper random secret
  2. Ensure no default values
  3. Check for whitespace/encoding issues

​
Database connection failed

  1. Verify POSTGRES_HOST is reachable
  2. Check POSTGRES_PASSWORD is correct
  3. Ensure database exists

​
CSRF validation failed

  1. Set APP_URL to your public URL
  2. Include protocol: https://chad.example.com
  3. Match the URL users access

​
Workers not starting

  1. Check BACKEND_WORKERS is a valid number
  2. Ensure adequate system resources
  3. Review startup logs for errors

​
Next Steps

Deployment

Production deployment guide

Health Monitoring

Monitor your deployment