Configuration Guide

This guide covers all configuration options for PadawanForge, including environment variables, database settings, and deployment configurations.

Environment Variables

Core Application Settings

Required Variables

# Application Identity
API_TOKEN=your_secure_token_here
APP_NAME=PadawanForge

# Session Configuration
SESSION_DURATION=420
DEFAULT_DIFFICULTY=basic

# Database Configuration
DATABASE_URL=your_d1_database_url

Optional Core Variables

# Application Settings
DEBUG_MODE=false
LOG_LEVEL=info
ENVIRONMENT=production

# Performance Tuning
MAX_CONNECTIONS=100
REQUEST_TIMEOUT=30000
CACHE_TTL=3600

OAuth Provider Configuration

Google OAuth

OAUTH_GOOGLE_CLIENT_ID=your_google_client_id
OAUTH_GOOGLE_CLIENT_SECRET=your_google_client_secret
OAUTH_GOOGLE_REDIRECT_URI=https://your-domain.com/api/auth/callback/google

Discord OAuth

OAUTH_DISCORD_CLIENT_ID=your_discord_client_id
OAUTH_DISCORD_CLIENT_SECRET=your_discord_client_secret
OAUTH_DISCORD_REDIRECT_URI=https://your-domain.com/api/auth/callback/discord

AI Configuration

Cloudflare Workers AI

# Default AI Provider
DEFAULT_AI_PROVIDER=cloudflare
DEFAULT_AI_MODEL=@cf/meta/llama-3.1-8b-instruct

# AI Settings
AI_TEMPERATURE=0.7
AI_MAX_TOKENS=150
AI_TIMEOUT=30000

Available AI Models (2025)

General Purpose Models:

@cf/meta/llama-3.3-70b-instruct-fp8-fast  # ⚡ 2-4x faster, premium quality
@cf/meta/llama-3.1-8b-instruct            # Default model, excellent for general tasks
@cf/meta/llama-3.2-3b-instruct            # 💰 Most cost-effective, fast

Specialized Models:

@cf/qwen/qwen2.5-coder-32b-instruct       # 💻 Code generation specialist
@cf/qwen/qwq-32b                          # 🧠 Advanced reasoning
@cf/mistralai/mistral-small-3.1-24b-instruct  # Vision + tool calling

Multimodal & Vision:

@cf/meta/llama-4-scout-17b-16e-instruct   # 🎨 Multimodal (text + images)
@cf/google/gemma-3-12b-it                 # 🌍 Multilingual + vision (140+ languages)

Storage Configuration

Cloudflare R2

R2_BUCKET_NAME=your_r2_bucket_name
R2_ACCESS_KEY_ID=your_r2_access_key
R2_SECRET_ACCESS_KEY=your_r2_secret_key
R2_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com

Cloudflare KV

SESSION_KV_NAMESPACE_ID=your_session_kv_namespace_id

Security Configuration

Session Security

SESSION_SECRET=your_session_secret_key
SESSION_COOKIE_SECURE=true
SESSION_COOKIE_HTTPONLY=true
SESSION_COOKIE_SAMESITE=strict

Rate Limiting

RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=60000
RATE_LIMIT_BURST=10

CORS Configuration

CORS_ORIGIN=https://your-domain.com
CORS_CREDENTIALS=true
CORS_METHODS=GET,POST,PUT,DELETE,OPTIONS

Database Configuration

D1 Database Setup

Wrangler Configuration

// wrangler.jsonc
{
  "name": "padawanforge",
  "compatibility_date": "2024-12-01",
  "compatibility_flags": ["nodejs_compat"],
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "padawanforge-db",
      "database_id": "your-database-id"
    }
  ],
  "durable_objects": {
    "bindings": [
      {
        "name": "CHAT_LOBBY",
        "class_name": "ChatLobby",
        "script_name": "padawanforge-beta"
      },
      {
        "name": "ROOM_MANAGER",
        "class_name": "RoomManager",
        "script_name": "padawanforge-beta"
      }
    ]
  },
  "workflows": [
    {
      "name": "padawanforge-beta-player-workflow",
      "binding": "PLAYER_WORKFLOW",
      "class_name": "PlayerWorkflow"
    }
  ],
  "kv_namespaces": [
    {
      "binding": "SESSION",
      "id": "your-session-kv-namespace-id"
    }
  ],
  "r2_buckets": [
    {
      "binding": "FILES",
      "bucket_name": "your-r2-bucket-name"
    }
  ],
  "ai": {
    "binding": "AI",
    "remote": true
  }
}

Important: The remote: true setting is required for Cloudflare Workers AI. Unlike other bindings, Workers AI has no local simulation and always connects to remote resources. Setting this explicitly eliminates warnings during development and makes the configuration clear.

Migration Configuration

# Migration settings
MIGRATION_BATCH_SIZE=100
MIGRATION_TIMEOUT=300000
MIGRATION_RETRY_ATTEMPTS=3

Deployment Configuration

Production Environment

Environment-Specific Variables

# Production Settings
NODE_ENV=production
ENVIRONMENT=production
DEBUG_MODE=false
LOG_LEVEL=warn

# Performance Settings
ENABLE_COMPRESSION=true
ENABLE_CACHING=true
CACHE_TTL=3600

Security Headers

# Security Configuration
ENABLE_HSTS=true
HSTS_MAX_AGE=31536000
ENABLE_CSP=true
CSP_POLICY="default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';"

Development Environment

Local Development Settings

# Development Settings
NODE_ENV=development
ENVIRONMENT=development
DEBUG_MODE=true
LOG_LEVEL=debug

# Local URLs
BASE_URL=http://localhost:4321
API_BASE_URL=http://localhost:4321/api

Development Tools

# Development Configuration
ENABLE_HOT_RELOAD=true
ENABLE_SOURCE_MAPS=true
ENABLE_DEBUG_LOGGING=true

Feature Flags

Experimental Features

# Feature Toggles
ENABLE_NPC_CHAT=true
ENABLE_LOBBY_SYSTEM=true
ENABLE_ADMIN_TOOLS=true
ENABLE_ANALYTICS=true
ENABLE_NOTIFICATIONS=true

AI Features

# AI Feature Configuration
ENABLE_COSTAR_PROMPTS=true
ENABLE_CONVERSATION_MEMORY=true
ENABLE_PERSONALITY_RESPONSES=true
ENABLE_KNOWLEDGE_BASE=true

Monitoring Configuration

Logging Configuration

# Logging Settings
LOG_FORMAT=json
LOG_LEVEL=info
LOG_SAMPLING_RATE=1.0
ENABLE_REQUEST_LOGGING=true
ENABLE_ERROR_LOGGING=true

Analytics Configuration

# Analytics Settings
ENABLE_USAGE_ANALYTICS=true
ENABLE_PERFORMANCE_MONITORING=true
ENABLE_ERROR_TRACKING=true
ANALYTICS_SAMPLE_RATE=0.1

Configuration Validation

Environment Validation

# Validate required variables
npm run validate:env

# Check configuration
npm run check:config

Configuration Testing

# Test database connection
npm run test:db

# Test AI providers
npm run test:ai

# Test OAuth providers
npm run test:oauth

Configuration Best Practices

Security Guidelines

  1. Never commit secrets to version control
  2. Use environment-specific configuration files
  3. Rotate secrets regularly
  4. Use strong, unique tokens for each service
  5. Enable HTTPS in production

Performance Guidelines

  1. Cache frequently accessed data
  2. Optimize database queries
  3. Use CDN for static assets
  4. Enable compression for responses
  5. Monitor resource usage

Development Guidelines

  1. Use descriptive variable names
  2. Document all configuration options
  3. Provide sensible defaults
  4. Validate configuration on startup
  5. Test configuration changes

Troubleshooting

Common Configuration Issues

Missing Environment Variables

# Check for missing variables
npm run validate:env

# Set required variables
export API_TOKEN=your_token
export DATABASE_URL=your_url

Database Connection Issues

# Test database connection
npm run test:db

# Check database permissions
npm run wrangler d1 execute padawan-db --command "SELECT 1"

OAuth Configuration Issues

# Validate OAuth settings
npm run test:oauth

# Check redirect URIs
echo $OAUTH_GOOGLE_REDIRECT_URI

AI Provider Issues

# Test AI connection
npm run test:ai

# Check API keys
echo $OPENAI_API_KEY

This configuration guide covers all aspects of setting up and customizing PadawanForge for your specific needs.

← Quick Start Guide Installation Guide →
PadawanForge v1.4.1