# WHOOSH Configuration Guide

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

## 📋 Quick Reference

| Category | Variables | Description |
|----------|-----------|-------------|
| [Database](#database-configuration) | `WHOOSH_DATABASE_*` | PostgreSQL connection and pooling |
| [Gitea Integration](#gitea-integration) | `WHOOSH_GITEA_*` | Repository monitoring and webhooks |
| [Security](#security-configuration) | `WHOOSH_JWT_*`, `WHOOSH_CORS_*` | Authentication and access control |
| [External Services](#external-services) | `WHOOSH_N8N_*`, `WHOOSH_BACKBEAT_*` | Third-party integrations |
| [Feature Flags](#feature-flags) | `WHOOSH_FEATURE_*` | Optional functionality toggles |
| [Docker Integration](#docker-integration) | `WHOOSH_DOCKER_*` | Container orchestration |
| [Observability](#observability-configuration) | `WHOOSH_OTEL_*`, `WHOOSH_LOG_*` | Tracing and logging |

## 🗄️ Database Configuration

### Core Database Settings

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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)

```bash
# 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)

```bash
# 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

```bash
# 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_AUDIT_REPORT.md)** - Security implementation details
- **[API Specification](API_SPECIFICATION.md)** - Complete API reference  
- **[Database Schema](DATABASE_SCHEMA.md)** - Database structure
- **[Deployment Guide](DEPLOYMENT.md)** - Production deployment procedures

For additional support, refer to the main [WHOOSH README](../README.md) or create an issue in the repository.