Configuration & Environment
Configure your Orcher workers and environment settings. Learn how to use orcher.toml for worker configuration and environment variables for runtime settings.
Choose Your SDK
Configuration Files:
• orcher.toml - Worker configuration
• .env - Environment variables
• Cargo.toml - Dependencies and metadata
Configuration File (orcher.toml)
The orcher.toml file configures your worker. Place it in your project root directory.
Basic Configuration
1# orcher.toml23[service]4name = "payment-service"5version = "1.0.0"6description = "Payment processing workflow service"78[orchestrator]9# URL of the Orcher orchestrator server10url = "http://localhost:9090"1112# Connection timeout13connect_timeout = "10s"1415# Request timeout16request_timeout = "30s"1718# Keep-alive interval19keep_alive = "60s"2021[worker]22# Port for the worker to listen on23port = 90802425# Maximum concurrent workflow executions26concurrency = 102728# Graceful shutdown timeout29shutdown_timeout = "30s"3031# Heartbeat interval32heartbeat_interval = "30s"3334[database]35# PostgreSQL connection URL36# Can be overridden by DATABASE_URL env var37url = "postgresql://postgres:postgres@localhost:5432/orcher_dev"3839# Maximum database connections40max_connections = 204142# Minimum idle connections43min_connections = 54445# Connection timeout46connect_timeout = "10s"4748[logging]49# Log level: trace, debug, info, warn, error50level = "info"5152# Log format: json, pretty53format = "pretty"5455# Log to file56file = "logs/orcher.log"5758# Enable structured logging59structured = true6061[metrics]62# Enable metrics collection63enabled = true6465# Prometheus metrics endpoint port66port = 90916768# Metrics path69path = "/metrics"7071[retry]72# Default retry configuration for tasks73max_retries = 374initial_delay = "5s"75max_delay = "5m"76backoff_multiplier = 2.07778[timeouts]79# Default workflow execution timeout80workflow_timeout = "1h"8182# Default task execution timeout83task_timeout = "5m"Production Configuration
1# orcher.production.toml23[service]4name = "payment-service"5version = "1.0.0"6environment = "production"78[orchestrator]9url = "https://orcher.mycompany.com:9090"10connect_timeout = "30s"11request_timeout = "60s"1213# TLS configuration14[orchestrator.tls]15enabled = true16cert_path = "/etc/ssl/certs/orcher-client.crt"17key_path = "/etc/ssl/private/orcher-client.key"18ca_path = "/etc/ssl/certs/ca.crt"1920[worker]21port = 908022concurrency = 502324# Health check endpoint25[worker.health]26enabled = true27port = 808028path = "/health"2930[database]31url = "postgresql://orcher_user:secure_password@db.mycompany.com:5432/orcher_prod"32max_connections = 10033min_connections = 103435# Connection pooling36[database.pool]37max_lifetime = "30m"38idle_timeout = "10m"3940[logging]41level = "warn"42format = "json"43file = "/var/log/orcher/service.log"4445# Send logs to external service46[logging.remote]47enabled = true48endpoint = "https://logs.mycompany.com"49api_key_env = "LOGGING_API_KEY"5051[metrics]52enabled = true53port = 90915455# Export to Prometheus56[metrics.prometheus]57enabled = true58push_gateway = "https://prometheus.mycompany.com"59push_interval = "30s"6061[security]62# Enable authentication63auth_enabled = true64auth_token_env = "ORCHER_AUTH_TOKEN"6566# Rate limiting67[security.rate_limit]68enabled = true69requests_per_second = 10070burst = 200Load Configuration
1use orcher::config::Config;23#[tokio::main]4async fn main() -> orcher::Result<()> {5 // Load from default location (orcher.toml)6 let config = Config::from_file("orcher.toml")?;7 8 // Or load from custom location9 let config = Config::from_file("config/production.toml")?;10 11 // Or load with environment override12 let config = Config::from_file("orcher.toml")?13 .with_env_override()?;14 15 // Use configuration16 let worker = WorkerBuilder::new()17 .config(config)18 .build()19 .await?;20 21 worker.run().await22}Environment Variables
Environment variables override configuration file settings and are useful for secrets and deployment-specific values.
Core Environment Variables
1# Orchestrator Connection2ORCHER_ORCHESTRATOR_URL="http://localhost:9090"34# Database5DATABASE_URL="postgresql://postgres:postgres@localhost:5432/orcher_dev"67# Worker Settings8ORCHER_WORKER_PORT=90809ORCHER_WORKER_CONCURRENCY=101011# Logging12RUST_LOG=info13ORCHER_LOG_FORMAT=json14ORCHER_LOG_FILE=/var/log/orcher/service.log1516# Metrics17ORCHER_METRICS_ENABLED=true18ORCHER_METRICS_PORT=90911920# Authentication21ORCHER_AUTH_TOKEN=your-secret-token2223# Timeouts24ORCHER_WORKFLOW_TIMEOUT=360025ORCHER_TASK_TIMEOUT=300Using .env File
Create a .env file in your project root:
1# .env (for local development)23# Orchestrator4ORCHER_ORCHESTRATOR_URL=http://localhost:909056# Database7DATABASE_URL=postgresql://postgres:postgres@localhost:5432/orcher_dev89# Worker10ORCHER_WORKER_PORT=908011ORCHER_WORKER_CONCURRENCY=101213# Logging14RUST_LOG=debug15ORCHER_LOG_FORMAT=pretty1617# External Services18STRIPE_API_KEY=sk_test_...19SENDGRID_API_KEY=SG...20AWS_REGION=us-east-1Load in your application:
1use dotenv::dotenv;23#[tokio::main]4async fn main() -> orcher::Result<()> {5 // Load .env file6 dotenv().ok();7 8 // Environment variables are now available9 let orchestrator_url = std::env::var("ORCHER_ORCHESTRATOR_URL")10 .unwrap_or_else(|_| "http://localhost:9090".to_string());11 12 let worker = WorkerBuilder::new()13 .server_url(&orchestrator_url)14 .task_queue("default")15 .build()16 .await?;17 18 worker.run().await19}Environment-Specific Files
1# .env.development2ORCHER_ORCHESTRATOR_URL=http://localhost:90903DATABASE_URL=postgresql://postgres:postgres@localhost:5432/orcher_dev4RUST_LOG=debug56# .env.staging7ORCHER_ORCHESTRATOR_URL=https://orcher-staging.mycompany.com:90908DATABASE_URL=postgresql://orcher_user:password@staging-db:5432/orcher_staging9RUST_LOG=info1011# .env.production12ORCHER_ORCHESTRATOR_URL=https://orcher.mycompany.com:909013DATABASE_URL=postgresql://orcher_user:password@prod-db:5432/orcher_prod14RUST_LOG=warnLoad based on environment:
1use dotenv::dotenv;2use std::env;34#[tokio::main]5async fn main() -> orcher::Result<()> {6 let environment = env::var("ENVIRONMENT")7 .unwrap_or_else(|_| "development".to_string());8 9 // Load environment-specific file10 let env_file = format!(".env.{}", environment);11 dotenv::from_filename(&env_file).ok();12 13 // Continue with setup14 // ...15}Multi-Environment Setup
Development Environment
1# config/development.toml23[service]4name = "payment-service"5environment = "development"67[orchestrator]8url = "http://localhost:9090"910[worker]11port = 908012concurrency = 51314[database]15url = "postgresql://postgres:postgres@localhost:5432/orcher_dev"16max_connections = 101718[logging]19level = "debug"20format = "pretty"2122[metrics]23enabled = true24port = 9091Run:
1# Set environment2export ENVIRONMENT=development34# Run with dev config5cargo run --bin payment-serviceStaging Environment
1# config/staging.toml23[service]4name = "payment-service"5environment = "staging"67[orchestrator]8url = "https://orcher-staging.mycompany.com:9090"910[worker]11port = 908012concurrency = 201314[database]15url = "postgresql://orcher_user:${DB_PASSWORD}@staging-db:5432/orcher_staging"16max_connections = 501718[logging]19level = "info"20format = "json"21file = "/var/log/orcher/service.log"2223[metrics]24enabled = true25port = 9091Deploy:
1# Set environment2export ENVIRONMENT=staging3export DB_PASSWORD=staging_password4export ORCHER_AUTH_TOKEN=staging_token56# Run7./payment-service --config config/staging.tomlProduction Environment
1# config/production.toml23[service]4name = "payment-service"5environment = "production"67[orchestrator]8url = "https://orcher.mycompany.com:9090"9connect_timeout = "30s"10request_timeout = "60s"1112[orchestrator.tls]13enabled = true14cert_path = "/etc/ssl/certs/orcher.crt"15key_path = "/etc/ssl/private/orcher.key"16ca_path = "/etc/ssl/certs/ca.crt"1718[worker]19port = 908020concurrency = 10021shutdown_timeout = "60s"2223[database]24url = "postgresql://orcher_user:${DB_PASSWORD}@prod-db:5432/orcher_prod"25max_connections = 20026min_connections = 202728[logging]29level = "warn"30format = "json"31file = "/var/log/orcher/service.log"3233[logging.remote]34enabled = true35endpoint = "https://logs.mycompany.com"36api_key_env = "LOGGING_API_KEY"3738[metrics]39enabled = true40port = 90914142[metrics.prometheus]43enabled = true44push_gateway = "https://prometheus.mycompany.com"4546[security]47auth_enabled = true48auth_token_env = "ORCHER_AUTH_TOKEN"4950[security.rate_limit]51enabled = true52requests_per_second = 1000Deploy with Docker:
1# Dockerfile2FROM rust:1.70 as builder3WORKDIR /app4COPY . .5RUN cargo build --release67FROM debian:bullseye-slim8COPY --from=builder /app/target/release/payment-service /usr/local/bin/9COPY config/production.toml /etc/orcher/config.toml1011# Install CA certificates12RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*1314CMD ["payment-service", "--config", "/etc/orcher/config.toml"]Docker Compose:
1version: '3.8'23services:4 payment-service:5 build: .6 environment:7 - ENVIRONMENT=production8 - DATABASE_URL=${DATABASE_URL}9 - ORCHER_AUTH_TOKEN=${ORCHER_AUTH_TOKEN}10 - LOGGING_API_KEY=${LOGGING_API_KEY}11 ports:12 - "9080:9080"13 - "9091:9091"14 volumes:15 - ./logs:/var/log/orcher16 - ./certs:/etc/ssl/certs17 restart: unless-stoppedSecrets Management
Using Environment Variables
1use std::env;23#[tokio::main]4async fn main() -> orcher::Result<()> {5 // Load secrets from environment6 let db_password = env::var("DATABASE_PASSWORD")7 .expect("DATABASE_PASSWORD must be set");8 9 let auth_token = env::var("ORCHER_AUTH_TOKEN")10 .expect("ORCHER_AUTH_TOKEN must be set");11 12 let stripe_key = env::var("STRIPE_API_KEY")13 .expect("STRIPE_API_KEY must be set");14 15 // Build database URL with password16 let database_url = format!(17 "postgresql://orcher_user:{}@db:5432/orcher_prod",18 db_password19 );20 21 // Secrets like `db_password` and `stripe_key` are used by your task22 // implementations (which own the side effects); the worker itself only23 // needs the orchestrator URL and, optionally, an API key.24 let _ = &database_url;25 let worker = WorkerBuilder::new()26 .server_url("http://localhost:50051")27 .task_queue("default")28 .api_key(&auth_token)29 .build()30 .await?;31 32 worker.run().await33}Using HashiCorp Vault
1use vaultrs::client::{VaultClient, VaultClientSettingsBuilder};23async fn load_secrets_from_vault() -> Result<Secrets> {4 // Connect to Vault5 let client = VaultClient::new(6 VaultClientSettingsBuilder::default()7 .address("https://vault.mycompany.com")8 .token(env::var("VAULT_TOKEN")?)9 .build()?10 )?;11 12 // Read secrets13 let db_secret = client14 .kv2("secret/orcher")15 .read("database")16 .await?;17 18 let api_secret = client19 .kv2("secret/orcher")20 .read("api-keys")21 .await?;22 23 Ok(Secrets {24 database_url: db_secret.data["url"].clone(),25 stripe_key: api_secret.data["stripe"].clone(),26 })27}2829#[tokio::main]30async fn main() -> orcher::Result<()> {31 let secrets = load_secrets_from_vault().await?;32 33 let worker = WorkerBuilder::new()34 .database_url(&secrets.database_url)35 .build()36 .await?;37 38 worker.run().await39}Using AWS Secrets Manager
1use aws_sdk_secretsmanager::Client;23async fn load_secrets_from_aws() -> Result<Secrets> {4 let config = aws_config::load_from_env().await;5 let client = Client::new(&config);6 7 // Get database credentials8 let db_secret = client9 .get_secret_value()10 .secret_id("orcher/database")11 .send()12 .await?;13 14 let db_creds: DbCredentials = serde_json::from_str(15 db_secret.secret_string().unwrap()16 )?;17 18 // Get API keys19 let api_secret = client20 .get_secret_value()21 .secret_id("orcher/api-keys")22 .send()23 .await?;24 25 let api_keys: ApiKeys = serde_json::from_str(26 api_secret.secret_string().unwrap()27 )?;28 29 Ok(Secrets {30 database_url: format!(31 "postgresql://{}:{}@{}:{}/{}",32 db_creds.username,33 db_creds.password,34 db_creds.host,35 db_creds.port,36 db_creds.database37 ),38 stripe_key: api_keys.stripe,39 })40}Configuration Validation
1use orcher::config::Config;2use serde::Deserialize;34#[derive(Debug, Deserialize)]5struct ValidatedConfig {6 #[serde(deserialize_with = "validate_url")]7 orchestrator_url: String,8 9 #[serde(deserialize_with = "validate_port")]10 worker_port: u16,11 12 #[serde(deserialize_with = "validate_concurrency")]13 concurrency: usize,14}1516fn validate_url<'de, D>(deserializer: D) -> Result<String, D::Error>17where18 D: serde::Deserializer<'de>,19{20 let url = String::deserialize(deserializer)?;21 url::Url::parse(&url)22 .map_err(serde::de::Error::custom)?;23 Ok(url)24}2526fn validate_port<'de, D>(deserializer: D) -> Result<u16, D::Error>27where28 D: serde::Deserializer<'de>,29{30 let port = u16::deserialize(deserializer)?;31 if port < 1024 {32 return Err(serde::de::Error::custom("Port must be >= 1024"));33 }34 Ok(port)35}3637fn validate_concurrency<'de, D>(deserializer: D) -> Result<usize, D::Error>38where39 D: serde::Deserializer<'de>,40{41 let concurrency = usize::deserialize(deserializer)?;42 if concurrency == 0 || concurrency > 1000 {43 return Err(serde::de::Error::custom(44 "Concurrency must be between 1 and 1000"45 ));46 }47 Ok(concurrency)48}Best Practices
1. Never Commit Secrets
1# .gitignore2.env3.env.*4!.env.example5config/**/secrets.toml6*.key7*.pem2. Use Environment-Specific Configs
1config/2├── base.toml # Shared configuration3├── development.toml # Dev overrides4├── staging.toml # Staging overrides5└── production.toml # Production overrides3. Document Required Variables
1# .env.example2# Copy to .env and fill in values34# Orchestrator Connection5ORCHER_ORCHESTRATOR_URL=http://localhost:909067# Database8DATABASE_URL=postgresql://postgres:postgres@localhost:5432/orcher_dev910# External Services (get from your dashboard)11STRIPE_API_KEY=sk_test_...12SENDGRID_API_KEY=SG...1314# Optional: Monitoring15SENTRY_DSN=16DATADOG_API_KEY=4. Validate Configuration on Startup
1#[tokio::main]2async fn main() -> orcher::Result<()> {3 // Load and validate config4 let config = Config::from_file("orcher.toml")?5 .with_env_override()?6 .validate()?;7 8 // Log configuration (without secrets)9 tracing::info!("Starting with configuration: {:?}", config.safe_debug());10 11 // Continue startup12 // ...13}5. Use Type-Safe Configuration
1use serde::Deserialize;23#[derive(Debug, Deserialize)]4struct AppConfig {5 worker: WorkerConfig,6 orchestrator: OrchestratorConfig,7 database: DatabaseConfig,8}910impl AppConfig {11 fn load() -> Result<Self> {12 let config_path = env::var("CONFIG_PATH")13 .unwrap_or_else(|_| "orcher.toml".to_string());14 15 let contents = std::fs::read_to_string(config_path)?;16 let mut config: AppConfig = toml::from_str(&contents)?;17 18 // Override with env vars19 config.apply_env_overrides()?;20 21 Ok(config)22 }23}Troubleshooting
Configuration Not Loading
1# Check file exists2ls -la orcher.toml34# Check file permissions5chmod 644 orcher.toml67# Verify TOML syntax8toml-check orcher.toml910# Enable debug logging11RUST_LOG=orcher::config=debug cargo runEnvironment Variables Not Working
1# Check variable is set2echo $ORCHER_ORCHESTRATOR_URL34# List all Orcher variables5env | grep ORCHER67# Source .env file manually8set -a && source .env && set +aDatabase Connection Issues
1# Test database connection2psql $DATABASE_URL -c "SELECT 1"34# Check connection string format5# postgresql://[user[:password]@][host][:port][/dbname][?param1=value1&...]67# Common issues:8# - Wrong password9# - Database doesn't exist10# - Host not reachable11# - Port blocked by firewallNext Steps
Workflow Development
Debugging Workflows
Production Deployment
Learn More
• CLI Reference - Complete CLI commands and options • Security Best Practices - Secure your configuration • Quickstart Repository - See configuration in action