Configuration Priority & Environments
Configuration Priority
The orchestrator applies settings in this precedence order:
- CLI flags (highest priority)
- Environment variables
- Config file (TOML, via
--configorORCHER_ORCHESTRATOR_CONFIG) - Built-in defaults (lowest priority)
This means you can set base configuration in a file, override specific values with environment variables (useful for secrets like DATABASE_URL), and further override with CLI flags for testing.
Development vs Production
Development Defaults
The orchestrator uses more aggressive timeouts in debug builds:
| Setting | Development | Production |
|---|---|---|
claim_timeout_secs | 60 (1 min) | 300 (5 min) |
reclaim_interval_secs | 5 | 10 |
poll_timeout_secs | 30 | 60 |
log_format | compact | json |
Or use OrchestratorConfig::for_development() programmatically for shorter timeouts and aggressive reclaim intervals.
Minimal Production Configuration
The minimum required for production:
1DATABASE_URL="postgresql://orcher:PASSWORD@pgbouncer:6432/orcher?sslmode=require" \2REDIS_URL="redis://redis:6379" \3LOG_FORMAT=json \4./orchestratorEverything else uses sensible defaults. Add a TOML config file only when you need to tune polling, timeouts, retry, or security settings.
Full Production Example
1[server]2grpc_addr = "0.0.0.0:50051"3http_addr = "0.0.0.0:8001"4max_concurrent_streams = 100056[orchestrator]7max_workers = 1008max_concurrent_tasks = 10009heartbeat_timeout_secs = 901011[storage]12database_url = "postgresql://orcher:PASSWORD@pgbouncer:6432/orcher?sslmode=require"13redis_url = "redis://redis:6379"1415[logging]16level = "info"17format = "json"1819[health]20readiness_enabled = true21liveness_enabled = true2223[polling]24claim_timeout_secs = 30025claim_query_timeout_ms = 200026poll_timeout_secs = 6027reclaim_interval_secs = 1028enable_notifications = true29batch_claim_size = 103031[timeout_watcher]32enabled = true33poll_interval_secs = 3034batch_size = 10035grace_period_secs = 53637[workflow_retry]38enabled = true39default_max_attempts = 340default_initial_backoff_secs = 141default_backoff_multiplier = 2.042default_max_backoff_secs = 3004344[background_jobs]45metrics_enabled = true46metrics_interval_secs = 360047retention_enabled = true48retention_interval_secs = 864004950[background_jobs.retention_days]51workflow_executions = 9052execution_logs = 3053journal_entries = 9054task_executions = 9055outbox_queue = 75657[security]58auth_mode = "api-key"59api_key_cache_ttl_secs = 30060api_key_cache_max_entries = 10000Next Steps
- Configuration Overview — Orchestrator CLI flags and environment variables
- TOML Configuration Reference — Full TOML config file reference
- Docker — Docker Compose setup
- Kubernetes — Kubernetes manifests reference
- Cloud Platforms — Deploy to AWS, GCP, and Azure
- Logging — Logging format and level configuration
- Metrics — Prometheus metrics reference