Configuration

Configuration Overview

CodeChunking uses Viper for hierarchical configuration. Values may come from (highest priority first):

1. Command-line flags
2. Environment variables (prefix CODECHUNK_)
3. Config files (./configs/config.yaml, ./configs/config.dev.yaml, ./configs/config.prod.yaml)
4. Built-in defaults

Config file path can be set with --config (defaults to ./configs/config.yaml).

CLI flags

• --config: Path to YAML config
• --log-level: debug|info|warn|error|fatal (default: info)
• --log-format: json|text (default: json)

Environment variables

• Prefix: CODECHUNK_; dots become underscores. Example: database.user → CODECHUNK_DATABASE_USER.
• Explicit bindings exist for API middleware toggles:
  • CODECHUNK_API_ENABLE_DEFAULT_MIDDLEWARE
  • CODECHUNK_API_ENABLE_CORS
  • CODECHUNK_API_ENABLE_SECURITY_HEADERS
  • CODECHUNK_API_ENABLE_LOGGING
  • CODECHUNK_API_ENABLE_ERROR_HANDLING

Top-level sections

• API Configuration: API server host, port, timeouts, middleware toggles
• Worker Configuration: concurrency, queue group, job timeout
• Database Configuration: connection settings and pool sizes
• NATS Configuration: connection and reconnect policy
• Gemini Configuration: embedding model settings and API key
• Logging Configuration: level and format
• Git Configuration: cloning behavior, timeouts, retries, workspace cleanup (optional)

Defaults (from code)

• api: host=0.0.0.0, port=8080, read_timeout=10s, write_timeout=10s
• worker: concurrency=5, queue_group=workers, job_timeout=30m
• database: host=localhost, port=5432, name=codechunking, sslmode=disable, max_connections=25, max_idle_connections=5
• nats: url=nats://localhost:4222, max_reconnects=5, reconnect_wait=2s
• log: level=info, format=json
• git: see Git Configuration for defaults

Validation rules (from code)

• database.user is required
• database.name is required
• database.port must be 1..65535
• worker.concurrency must be ≥ 1
• If log.level is error or fatal, gemini.api_key is required

Related files

• internal/config/config.go (Config, API/Worker/Database/NATS/Gemini/Log structs and validation)
• cmd/root.go (Viper defaults, env bindings, --config flag)
• configs/config.yaml (base), configs/config.dev.yaml, configs/config.prod.yaml
• .env.example (environment variable examples)

Examples

YAML (configs/config.yaml)

api:
  host: 0.0.0.0
  port: 8080
  read_timeout: 10s
  write_timeout: 10s
  # Optional middleware toggles (all default to true if omitted)
  # enable_default_middleware: true
  # enable_cors: true
  # enable_security_headers: true
  # enable_logging: true
  # enable_error_handling: true

worker:
  concurrency: 5
  queue_group: workers
  job_timeout: 30m

database:
  host: localhost
  port: 5432
  user: dev
  password: dev
  name: codechunking
  sslmode: disable
  max_connections: 25
  max_idle_connections: 5

nats:
  url: nats://localhost:4222
  max_reconnects: 5
  reconnect_wait: 2s

gemini:
  api_key: ${CODECHUNK_GEMINI_API_KEY}
  model: gemini-embedding-001
  max_retries: 3
  timeout: 30s

log:
  level: info
  format: json

# Optional: Git behavior (see dedicated page for details)
# git:
#   shallow_clone_threshold_mb: 100
#   default_depth: 1
#   default_timeout: 30m

Environment overrides

export CODECHUNK_DATABASE_USER=myuser
export CODECHUNK_DATABASE_PASSWORD=mypass
export CODECHUNK_GEMINI_API_KEY=your-api-key
export CODECHUNK_LOG_LEVEL=debug
export CODECHUNK_API_ENABLE_SECURITY_HEADERS=false

Run with explicit config

codechunking api --config configs/config.dev.yaml