WHOOSH/docs/CONFIGURATION.md

WHOOSH Configuration Guide

This guide provides comprehensive documentation for all WHOOSH configuration options and environment variables.

📋 Quick Reference

Category	Variables	Description
Database	WHOOSH_DATABASE_*	PostgreSQL connection and pooling
Gitea Integration	WHOOSH_GITEA_*	Repository monitoring and webhooks
Security	WHOOSH_JWT_*, WHOOSH_CORS_*	Authentication and access control
External Services	WHOOSH_N8N_*, WHOOSH_BACKBEAT_*	Third-party integrations
Feature Flags	WHOOSH_FEATURE_*	Optional functionality toggles
Docker Integration	WHOOSH_DOCKER_*	Container orchestration
Observability	WHOOSH_OTEL_*, WHOOSH_LOG_*	Tracing and logging

🗄️ Database Configuration

Core Database Settings

# Primary database connection
WHOOSH_DATABASE_URL=postgres://username:password@host:5432/database?sslmode=require

# Alternative: Individual components
WHOOSH_DB_HOST=localhost
WHOOSH_DB_PORT=5432
WHOOSH_DB_NAME=whoosh
WHOOSH_DB_USER=whoosh_user
WHOOSH_DB_PASSWORD=secure_password
WHOOSH_DB_SSLMODE=require

Connection Pool Settings

# Connection pool configuration
WHOOSH_DB_MAX_OPEN_CONNS=25          # Maximum open connections
WHOOSH_DB_MAX_IDLE_CONNS=10          # Maximum idle connections
WHOOSH_DB_CONN_MAX_LIFETIME=300s     # Connection lifetime
WHOOSH_DB_CONN_MAX_IDLE_TIME=60s     # Maximum idle time

Migration Settings

# Database migration configuration
WHOOSH_DB_MIGRATE_ON_START=true      # Run migrations on startup
WHOOSH_MIGRATION_PATH=./migrations   # Migration files location

🔧 Gitea Integration

Basic Gitea Settings

# Gitea instance configuration
WHOOSH_GITEA_URL=https://gitea.example.com
WHOOSH_GITEA_TOKEN_FILE=/run/secrets/gitea_token    # Recommended for production
WHOOSH_GITEA_TOKEN=your-gitea-api-token             # Alternative for development

# Webhook configuration
WHOOSH_WEBHOOK_SECRET_FILE=/run/secrets/webhook_secret
WHOOSH_WEBHOOK_SECRET=your-webhook-secret

Repository Monitoring

# Repository sync behavior
WHOOSH_GITEA_EAGER_FILTER=true       # API-level filtering (recommended)
WHOOSH_GITEA_FULL_RESCAN=false       # Complete vs incremental scan
WHOOSH_GITEA_DEBUG_URLS=false        # Log exact API URLs for debugging

# Retry and timeout settings
WHOOSH_GITEA_MAX_RETRIES=3           # API retry attempts
WHOOSH_GITEA_RETRY_DELAY=2s          # Delay between retries
WHOOSH_GITEA_REQUEST_TIMEOUT=30s     # API request timeout

Label and Issue Configuration

# Label management
WHOOSH_CHORUS_TASK_LABELS=chorus-entrypoint,bzzz-task
WHOOSH_AUTO_CREATE_LABELS=true       # Auto-create missing labels
WHOOSH_ENABLE_CHORUS_INTEGRATION=true

# Issue processing
WHOOSH_ISSUE_BATCH_SIZE=50           # Issues per API request
WHOOSH_ISSUE_SYNC_INTERVAL=300s      # Sync frequency

🔐 Security Configuration

JWT Authentication

# JWT token configuration
WHOOSH_JWT_SECRET_FILE=/run/secrets/jwt_secret      # Recommended
WHOOSH_JWT_SECRET=your-jwt-secret                   # Alternative
WHOOSH_JWT_EXPIRATION=24h            # Token expiration
WHOOSH_JWT_ISSUER=whoosh             # Token issuer
WHOOSH_JWT_ALGORITHM=HS256           # Signing algorithm

CORS Settings

# CORS configuration - NEVER use * in production
WHOOSH_CORS_ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com
WHOOSH_CORS_ALLOWED_METHODS=GET,POST,PUT,DELETE,OPTIONS
WHOOSH_CORS_ALLOWED_HEADERS=Authorization,Content-Type,X-Requested-With
WHOOSH_CORS_ALLOW_CREDENTIALS=true
WHOOSH_CORS_MAX_AGE=86400            # Preflight cache duration

Rate Limiting

# Rate limiting configuration
WHOOSH_RATE_LIMIT_ENABLED=true
WHOOSH_RATE_LIMIT_REQUESTS=100       # Requests per window
WHOOSH_RATE_LIMIT_WINDOW=60s         # Rate limiting window
WHOOSH_RATE_LIMIT_CLEANUP_INTERVAL=300s  # Cleanup frequency

Input Validation

# Request validation settings
WHOOSH_MAX_REQUEST_SIZE=1048576      # 1MB default request size
WHOOSH_MAX_WEBHOOK_SIZE=10485760     # 10MB for webhooks
WHOOSH_VALIDATION_STRICT=true        # Enable strict validation

Service Tokens

# Service-to-service authentication
WHOOSH_SERVICE_TOKEN_FILE=/run/secrets/service_token
WHOOSH_SERVICE_TOKEN=your-service-token
WHOOSH_SERVICE_TOKEN_HEADER=X-Service-Token

🔗 External Services

N8N Integration

# N8N workflow automation
WHOOSH_N8N_BASE_URL=https://n8n.example.com
WHOOSH_N8N_AUTH_TOKEN_FILE=/run/secrets/n8n_token
WHOOSH_N8N_AUTH_TOKEN=your-n8n-token
WHOOSH_N8N_TIMEOUT=60s               # Request timeout
WHOOSH_N8N_MAX_RETRIES=3             # Retry attempts

BackBeat Monitoring

# BackBeat performance monitoring
WHOOSH_BACKBEAT_URL=http://backbeat:3001
WHOOSH_BACKBEAT_ENABLED=true
WHOOSH_BACKBEAT_TOKEN_FILE=/run/secrets/backbeat_token
WHOOSH_BACKBEAT_BEAT_INTERVAL=30s    # Beat frequency
WHOOSH_BACKBEAT_TIMEOUT=10s          # Request timeout

🚩 Feature Flags

LLM Integration

# AI vs Heuristic classification
WHOOSH_FEATURE_LLM_CLASSIFICATION=false     # Enable LLM classification
WHOOSH_FEATURE_LLM_SKILL_ANALYSIS=false     # Enable LLM skill analysis
WHOOSH_FEATURE_LLM_TEAM_MATCHING=false      # Enable LLM team matching
WHOOSH_FEATURE_ENABLE_ANALYSIS_LOGGING=true # Log analysis details
WHOOSH_FEATURE_ENABLE_FAILSAFE_FALLBACK=true # Fallback to heuristics

Experimental Features

# Advanced features (use with caution)
WHOOSH_FEATURE_ADVANCED_P2P=false           # Enhanced P2P discovery
WHOOSH_FEATURE_CROSS_COUNCIL_COORDINATION=false
WHOOSH_FEATURE_PREDICTIVE_FORMATION=false   # ML-based team formation
WHOOSH_FEATURE_AUTO_SCALING=false           # Automatic agent scaling

🐳 Docker Integration

Docker Swarm Settings

# Docker daemon connection
WHOOSH_DOCKER_ENABLED=true
WHOOSH_DOCKER_HOST=unix:///var/run/docker.sock
WHOOSH_DOCKER_VERSION=1.41           # Docker API version
WHOOSH_DOCKER_TIMEOUT=60s            # Operation timeout

# Swarm-specific settings
WHOOSH_SWARM_NETWORK=chorus_default  # Swarm network name
WHOOSH_SWARM_CONSTRAINTS=node.role==worker  # Placement constraints

Agent Deployment

# CHORUS agent deployment
WHOOSH_AGENT_IMAGE=anthonyrawlins/chorus:latest
WHOOSH_AGENT_MEMORY_LIMIT=2048m      # Memory limit per agent
WHOOSH_AGENT_CPU_LIMIT=1.0           # CPU limit per agent
WHOOSH_AGENT_RESTART_POLICY=on-failure
WHOOSH_AGENT_MAX_RESTARTS=3

Volume and Secret Mounts

# Shared volumes
WHOOSH_PROMPTS_PATH=/rust/containers/WHOOSH/prompts
WHOOSH_SHARED_DATA_PATH=/rust/shared

# Docker secrets
WHOOSH_DOCKER_SECRET_PREFIX=whoosh_  # Secret naming prefix

📊 Observability Configuration

OpenTelemetry Tracing

# OpenTelemetry configuration
WHOOSH_OTEL_ENABLED=true
WHOOSH_OTEL_SERVICE_NAME=whoosh
WHOOSH_OTEL_SERVICE_VERSION=1.0.0
WHOOSH_OTEL_ENDPOINT=http://jaeger:14268/api/traces
WHOOSH_OTEL_SAMPLER_RATIO=1.0        # Sampling ratio (0.0-1.0)
WHOOSH_OTEL_BATCH_TIMEOUT=5s         # Batch export timeout

Logging Configuration

# Logging settings
WHOOSH_LOG_LEVEL=info                # trace, debug, info, warn, error
WHOOSH_LOG_FORMAT=json               # json or text
WHOOSH_LOG_OUTPUT=stdout             # stdout, stderr, or file path
WHOOSH_LOG_CALLER=false              # Include caller information
WHOOSH_LOG_TIMESTAMP=true            # Include timestamps

Metrics and Health

# Prometheus metrics
WHOOSH_METRICS_ENABLED=true
WHOOSH_METRICS_PATH=/metrics         # Metrics endpoint path
WHOOSH_METRICS_NAMESPACE=whoosh      # Metrics namespace

# Health check configuration
WHOOSH_HEALTH_CHECK_INTERVAL=30s     # Internal health check frequency
WHOOSH_HEALTH_TIMEOUT=10s            # Health check timeout

🌐 Server Configuration

HTTP Server Settings

# Server bind configuration
WHOOSH_SERVER_HOST=0.0.0.0           # Bind address
WHOOSH_SERVER_PORT=8080              # Listen port
WHOOSH_SERVER_READ_TIMEOUT=30s       # Request read timeout
WHOOSH_SERVER_WRITE_TIMEOUT=30s      # Response write timeout
WHOOSH_SERVER_IDLE_TIMEOUT=60s       # Idle connection timeout
WHOOSH_SERVER_MAX_HEADER_BYTES=1048576 # Max header size

TLS Configuration

# TLS/SSL settings (optional)
WHOOSH_TLS_ENABLED=false
WHOOSH_TLS_CERT_FILE=/path/to/cert.pem
WHOOSH_TLS_KEY_FILE=/path/to/key.pem
WHOOSH_TLS_MIN_VERSION=1.2           # Minimum TLS version

🔍 P2P Discovery Configuration

Service Discovery

# P2P discovery settings
WHOOSH_P2P_DISCOVERY_ENABLED=true
WHOOSH_P2P_KNOWN_ENDPOINTS=chorus:8081,agent1:8081,agent2:8081
WHOOSH_P2P_SERVICE_PORTS=8081,8082,8083
WHOOSH_P2P_DOCKER_ENABLED=true       # Docker Swarm discovery

# Health checking
WHOOSH_P2P_HEALTH_TIMEOUT=5s         # Agent health check timeout
WHOOSH_P2P_RETRY_ATTEMPTS=3          # Health check retries
WHOOSH_P2P_DISCOVERY_INTERVAL=60s    # Discovery cycle frequency

Agent Filtering

# Agent capability filtering
WHOOSH_P2P_REQUIRED_CAPABILITIES=council,reasoning
WHOOSH_P2P_MIN_AGENT_VERSION=1.0.0   # Minimum agent version
WHOOSH_P2P_FILTER_INACTIVE=true      # Filter inactive agents

📁 Environment File Examples

Production Environment (.env.production)

# Production configuration template
# Copy to .env and customize

# Database
WHOOSH_DATABASE_URL=postgres://whoosh:${DB_PASSWORD}@postgres:5432/whoosh?sslmode=require
WHOOSH_DB_MAX_OPEN_CONNS=50
WHOOSH_DB_MAX_IDLE_CONNS=20

# Security (use Docker secrets in production)
WHOOSH_JWT_SECRET_FILE=/run/secrets/jwt_secret
WHOOSH_WEBHOOK_SECRET_FILE=/run/secrets/webhook_secret
WHOOSH_CORS_ALLOWED_ORIGINS=https://app.company.com,https://admin.company.com

# Gitea
WHOOSH_GITEA_URL=https://git.company.com
WHOOSH_GITEA_TOKEN_FILE=/run/secrets/gitea_token
WHOOSH_GITEA_EAGER_FILTER=true

# External services
WHOOSH_N8N_BASE_URL=https://workflows.company.com
WHOOSH_BACKBEAT_URL=http://backbeat:3001

# Observability
WHOOSH_OTEL_ENABLED=true
WHOOSH_OTEL_ENDPOINT=http://jaeger:14268/api/traces
WHOOSH_LOG_LEVEL=info

# Feature flags (conservative defaults)
WHOOSH_FEATURE_LLM_CLASSIFICATION=false
WHOOSH_FEATURE_LLM_SKILL_ANALYSIS=false

# Docker
WHOOSH_DOCKER_ENABLED=true

Development Environment (.env.development)

# Development configuration
# More permissive settings for local development

# Database
WHOOSH_DATABASE_URL=postgres://whoosh:password@localhost:5432/whoosh?sslmode=disable

# Security (relaxed for development)
WHOOSH_JWT_SECRET=dev-secret-change-in-production
WHOOSH_WEBHOOK_SECRET=dev-webhook-secret
WHOOSH_CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8080

# Gitea
WHOOSH_GITEA_URL=http://localhost:3000
WHOOSH_GITEA_TOKEN=your-dev-token
WHOOSH_GITEA_DEBUG_URLS=true

# Logging (verbose for debugging)
WHOOSH_LOG_LEVEL=debug
WHOOSH_LOG_CALLER=true

# Feature flags (enable experimental features)
WHOOSH_FEATURE_LLM_CLASSIFICATION=true
WHOOSH_FEATURE_ENABLE_ANALYSIS_LOGGING=true

# Docker (disabled for local development)
WHOOSH_DOCKER_ENABLED=false

🔧 Configuration Validation

WHOOSH validates configuration on startup and provides detailed error messages for invalid settings:

Required Variables

• WHOOSH_DATABASE_URL or individual DB components
• WHOOSH_GITEA_URL
• WHOOSH_GITEA_TOKEN or WHOOSH_GITEA_TOKEN_FILE

Common Validation Errors

# Invalid database URL
ERROR: Invalid database URL format

# Missing secrets
ERROR: JWT secret not found. Set WHOOSH_JWT_SECRET or WHOOSH_JWT_SECRET_FILE

# Invalid CORS configuration
ERROR: CORS wildcard (*) not allowed in production. Set specific origins.

# Docker connection failed
WARNING: Docker not available. Agent deployment disabled.

🚀 Best Practices

Production Deployment

1. Use Docker secrets for all sensitive data
2. Set specific CORS origins (never use wildcards)
3. Enable rate limiting and input validation
4. Configure appropriate timeouts for your network
5. Enable observability (tracing, metrics, logs)
6. Use conservative feature flags until tested

Security Hardening

1. Rotate secrets regularly using automated processes
2. Use TLS everywhere in production
3. Monitor security logs for suspicious activity
4. Keep dependency versions updated
5. Review access logs regularly

Performance Optimization

1. Tune database connection pools based on load
2. Configure appropriate cache settings
3. Use CDN for static assets if applicable
4. Monitor resource usage and scale accordingly
5. Enable compression for large responses

Troubleshooting

1. Enable debug logging temporarily for issues
2. Check health endpoints for component status
3. Monitor trace data for request flow issues
4. Validate configuration before deployment
5. Test in staging environment first

---

📚 Related Documentation

• Security Audit - Security implementation details
• API Specification - Complete API reference
• Database Schema - Database structure
• Deployment Guide - Production deployment procedures

For additional support, refer to the main WHOOSH README or create an issue in the repository.