Skip to content

Configuration Guide

Learn how to configure FireBreak for different environments.

Configuration Overview

FireBreak uses a multi-layered configuration approach:

  1. Wrangler Configuration (wrangler.jsonc) - Worker settings, bindings
  2. Environment Variables - API keys, secrets
  3. Feature Flags - Toggle features per environment
  4. Tenant Configuration - Multi-tenant settings

Wrangler Configuration

The backend/wrangler.jsonc file configures Cloudflare Workers:

{
  "name": "firestorm-backend-local",
  "main": "src/index.py",
  "compatibility_date": "2024-01-01",
  "compatibility_flags": ["python_workers"],

  "vars": {
    "ENVIRONMENT": "local",
    "API_VERSION": "v1",
    "DEBUG": "true"
  },

  "kv_namespaces": [],
  "r2_buckets": [],
  "d1_databases": []
}

Environment-Specific Configuration

{
  "name": "firestorm-backend-local",
  "vars": {
    "ENVIRONMENT": "local",
    "DEBUG": "true"
  }
}

{
  "name": "firestorm-backend-staging",
  "vars": {
    "ENVIRONMENT": "staging",
    "DEBUG": "false"
  },
  "routes": [
    {
      "pattern": "api-staging.firebreakrisk.com/*",
      "zone_name": "firebreakrisk.com"
    }
  ]
}

{
  "name": "firestorm-backend-production",
  "vars": {
    "ENVIRONMENT": "production",
    "DEBUG": "false"
  },
  "routes": [
    {
      "pattern": "api.firebreakrisk.com/*",
      "zone_name": "firebreakrisk.com"
    }
  ]
}

For full wrangler configuration details, see backend/wrangler.jsonc.

Environment Variables

Backend Environment Variables

# API Keys (optional for local development with mock data)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

# Cloudflare Settings
CLOUDFLARE_ACCOUNT_ID=...
CLOUDFLARE_API_TOKEN=...

# Feature Flags
ENABLE_MULTI_MODEL_CONSENSUS=true
ENABLE_DEBUG_LOGGING=false

Setting Secrets

For staging and production, use Wrangler to set secrets:

# Staging
wrangler secret put OPENAI_API_KEY --env staging
wrangler secret put ANTHROPIC_API_KEY --env staging

# Production
wrangler secret put OPENAI_API_KEY --env production
wrangler secret put ANTHROPIC_API_KEY --env production

# List secrets
wrangler secret list --env staging

Never Commit Secrets

Never commit API keys or secrets to version control. Use Wrangler secrets or environment variables.

Frontend Configuration

Frontend configuration is in frontend/core/.env:

# API Endpoint
VITE_API_BASE_URL=http://localhost:8787/api/v1

# Feature Flags
VITE_ENABLE_DEBUG=true
VITE_ENABLE_ANALYTICS=false

# Tenant
VITE_TENANT_ID=default

Environment-Specific Frontend Config

VITE_API_BASE_URL=http://localhost:8787/api/v1
VITE_ENABLE_DEBUG=true

VITE_API_BASE_URL=https://api-staging.firebreakrisk.com/api/v1
VITE_ENABLE_DEBUG=false
VITE_ENABLE_ANALYTICS=true

VITE_API_BASE_URL=https://api.firebreakrisk.com/api/v1
VITE_ENABLE_DEBUG=false
VITE_ENABLE_ANALYTICS=true

Resource Bindings

KV Namespaces

{
  "kv_namespaces": [
    {
      "binding": "CACHE",
      "id": "your-kv-namespace-id"
    }
  ]
}

R2 Buckets

{
  "r2_buckets": [
    {
      "binding": "PHOTOS",
      "bucket_name": "firestorm-photos-staging"
    }
  ]
}

D1 Databases

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "firestorm-staging",
      "database_id": "your-d1-database-id"
    }
  ]
}

Feature Flags

Feature flags allow you to toggle features per environment:

# backend/src/utils/feature_flags.py
def is_enabled(feature: str, env) -> bool:
    """Check if a feature is enabled"""
    flags = {
        'multi_model_consensus': env.ENABLE_MULTI_MODEL_CONSENSUS,
        'debug_logging': env.DEBUG,
        'rate_limiting': env.ENABLE_RATE_LIMITING,
    }
    return flags.get(feature, False)

Usage: 

from utils.feature_flags import is_enabled

if is_enabled('multi_model_consensus', env):
    # Use multi-model consensus
    result = await consensus_service.analyze(photo)
else:
    # Use single model
    result = await claude_service.analyze(photo)

CORS Configuration

Configure CORS for frontend-backend communication:

# backend/src/utils/cors.py
CORS_HEADERS = {
    'Access-Control-Allow-Origin': '*',  # Or specific origin
    'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
    'Access-Control-Allow-Headers': 'Content-Type, Authorization',
}

For production, restrict origins: 

allowed_origins = [
    'https://firebreakrisk.com',
    'https://staging.firebreakrisk.com'
]

Tenant Configuration

Multi-tenant settings (Sprint 2+):

{
  "tenants": {
    "acme-insurance": {
      "subdomain": "acme",
      "branding": {
        "primaryColor": "#FF6600",
        "logo": "https://..."
      }
    }
  }
}

See Multi-Tenant Guide for details.

Configuration Best Practices

1. Use Environment-Specific Values

// wrangler.jsonc
{
  "env": {
    "staging": {
      "vars": {
        "API_RATE_LIMIT": "100"
      }
    },
    "production": {
      "vars": {
        "API_RATE_LIMIT": "1000"
      }
    }
  }
}

2. Never Hardcode Secrets

❌ DON'T: 

api_key = "sk-1234567890abcdef"  # Hardcoded!

✅ DO: 

api_key = env.OPENAI_API_KEY  # From Wrangler secret

3. Use Feature Flags for Gradual Rollout

if is_enabled('new_feature', env) and env.ENVIRONMENT == 'staging':
    # Test new feature in staging first
    result = await new_feature_handler(request)
else:
    # Use existing implementation
    result = await old_handler(request)

4. Validate Configuration on Startup

async def validate_config(env):
    """Validate required configuration"""
    required_vars = ['OPENAI_API_KEY', 'CLOUDFLARE_ACCOUNT_ID']
    for var in required_vars:
        if not hasattr(env, var):
            raise ConfigError(f"Missing required variable: {var}")

Configuration Files Reference

File Purpose Environment
backend/wrangler.jsonc Backend Worker config All
frontend/core/.env Frontend environment vars Local
qa/pytest.ini Test configuration Testing
shared/api-contract.json API contract All

Troubleshooting

Issue: "Missing required variable"

Check that all required environment variables are set:

wrangler secret list --env staging

Issue: CORS errors in browser

Verify CORS headers in backend:

# Check response headers
response = Response(body, headers={
    'Access-Control-Allow-Origin': '*',
    'Content-Type': 'application/json'
})

Issue: Feature flag not working

Verify feature flag is set in wrangler.jsonc:

{
  "vars": {
    "ENABLE_FEATURE_NAME": "true"  // Must be string
  }
}

Next Steps

Additional Resources