Local Development

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.toml
2
3
[service]
4
name = "payment-service"
5
version = "1.0.0"
6
description = "Payment processing workflow service"
7
8
[orchestrator]
9
# URL of the Orcher orchestrator server
10
url = "http://localhost:9090"
11
12
# Connection timeout
13
connect_timeout = "10s"
14
15
# Request timeout
16
request_timeout = "30s"
17
18
# Keep-alive interval
19
keep_alive = "60s"
20
21
[worker]
22
# Port for the worker to listen on
23
port = 9080
24
25
# Maximum concurrent workflow executions
26
concurrency = 10
27
28
# Graceful shutdown timeout
29
shutdown_timeout = "30s"
30
31
# Heartbeat interval
32
heartbeat_interval = "30s"
33
34
[database]
35
# PostgreSQL connection URL
36
# Can be overridden by DATABASE_URL env var
37
url = "postgresql://postgres:postgres@localhost:5432/orcher_dev"
38
39
# Maximum database connections
40
max_connections = 20
41
42
# Minimum idle connections
43
min_connections = 5
44
45
# Connection timeout
46
connect_timeout = "10s"
47
48
[logging]
49
# Log level: trace, debug, info, warn, error
50
level = "info"
51
52
# Log format: json, pretty
53
format = "pretty"
54
55
# Log to file
56
file = "logs/orcher.log"
57
58
# Enable structured logging
59
structured = true
60
61
[metrics]
62
# Enable metrics collection
63
enabled = true
64
65
# Prometheus metrics endpoint port
66
port = 9091
67
68
# Metrics path
69
path = "/metrics"
70
71
[retry]
72
# Default retry configuration for tasks
73
max_retries = 3
74
initial_delay = "5s"
75
max_delay = "5m"
76
backoff_multiplier = 2.0
77
78
[timeouts]
79
# Default workflow execution timeout
80
workflow_timeout = "1h"
81
82
# Default task execution timeout
83
task_timeout = "5m"

Production Configuration

1
# orcher.production.toml
2
3
[service]
4
name = "payment-service"
5
version = "1.0.0"
6
environment = "production"
7
8
[orchestrator]
9
url = "https://orcher.mycompany.com:9090"
10
connect_timeout = "30s"
11
request_timeout = "60s"
12
13
# TLS configuration
14
[orchestrator.tls]
15
enabled = true
16
cert_path = "/etc/ssl/certs/orcher-client.crt"
17
key_path = "/etc/ssl/private/orcher-client.key"
18
ca_path = "/etc/ssl/certs/ca.crt"
19
20
[worker]
21
port = 9080
22
concurrency = 50
23
24
# Health check endpoint
25
[worker.health]
26
enabled = true
27
port = 8080
28
path = "/health"
29
30
[database]
31
url = "postgresql://orcher_user:secure_password@db.mycompany.com:5432/orcher_prod"
32
max_connections = 100
33
min_connections = 10
34
35
# Connection pooling
36
[database.pool]
37
max_lifetime = "30m"
38
idle_timeout = "10m"
39
40
[logging]
41
level = "warn"
42
format = "json"
43
file = "/var/log/orcher/service.log"
44
45
# Send logs to external service
46
[logging.remote]
47
enabled = true
48
endpoint = "https://logs.mycompany.com"
49
api_key_env = "LOGGING_API_KEY"
50
51
[metrics]
52
enabled = true
53
port = 9091
54
55
# Export to Prometheus
56
[metrics.prometheus]
57
enabled = true
58
push_gateway = "https://prometheus.mycompany.com"
59
push_interval = "30s"
60
61
[security]
62
# Enable authentication
63
auth_enabled = true
64
auth_token_env = "ORCHER_AUTH_TOKEN"
65
66
# Rate limiting
67
[security.rate_limit]
68
enabled = true
69
requests_per_second = 100
70
burst = 200

Load Configuration

1
use orcher::config::Config;
2
3
#[tokio::main]
4
async 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 location
9
let config = Config::from_file("config/production.toml")?;
10
11
// Or load with environment override
12
let config = Config::from_file("orcher.toml")?
13
.with_env_override()?;
14
15
// Use configuration
16
let worker = WorkerBuilder::new()
17
.config(config)
18
.build()
19
.await?;
20
21
worker.run().await
22
}

Environment Variables

Environment variables override configuration file settings and are useful for secrets and deployment-specific values.

Core Environment Variables

1
# Orchestrator Connection
2
ORCHER_ORCHESTRATOR_URL="http://localhost:9090"
3
4
# Database
5
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/orcher_dev"
6
7
# Worker Settings
8
ORCHER_WORKER_PORT=9080
9
ORCHER_WORKER_CONCURRENCY=10
10
11
# Logging
12
RUST_LOG=info
13
ORCHER_LOG_FORMAT=json
14
ORCHER_LOG_FILE=/var/log/orcher/service.log
15
16
# Metrics
17
ORCHER_METRICS_ENABLED=true
18
ORCHER_METRICS_PORT=9091
19
20
# Authentication
21
ORCHER_AUTH_TOKEN=your-secret-token
22
23
# Timeouts
24
ORCHER_WORKFLOW_TIMEOUT=3600
25
ORCHER_TASK_TIMEOUT=300

Using .env File

Create a .env file in your project root:

1
# .env (for local development)
2
3
# Orchestrator
4
ORCHER_ORCHESTRATOR_URL=http://localhost:9090
5
6
# Database
7
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/orcher_dev
8
9
# Worker
10
ORCHER_WORKER_PORT=9080
11
ORCHER_WORKER_CONCURRENCY=10
12
13
# Logging
14
RUST_LOG=debug
15
ORCHER_LOG_FORMAT=pretty
16
17
# External Services
18
STRIPE_API_KEY=sk_test_...
19
SENDGRID_API_KEY=SG...
20
AWS_REGION=us-east-1

Load in your application:

1
use dotenv::dotenv;
2
3
#[tokio::main]
4
async fn main() -> orcher::Result<()> {
5
// Load .env file
6
dotenv().ok();
7
8
// Environment variables are now available
9
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().await
19
}

Environment-Specific Files

1
# .env.development
2
ORCHER_ORCHESTRATOR_URL=http://localhost:9090
3
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/orcher_dev
4
RUST_LOG=debug
5
6
# .env.staging
7
ORCHER_ORCHESTRATOR_URL=https://orcher-staging.mycompany.com:9090
8
DATABASE_URL=postgresql://orcher_user:password@staging-db:5432/orcher_staging
9
RUST_LOG=info
10
11
# .env.production
12
ORCHER_ORCHESTRATOR_URL=https://orcher.mycompany.com:9090
13
DATABASE_URL=postgresql://orcher_user:password@prod-db:5432/orcher_prod
14
RUST_LOG=warn

Load based on environment:

1
use dotenv::dotenv;
2
use std::env;
3
4
#[tokio::main]
5
async fn main() -> orcher::Result<()> {
6
let environment = env::var("ENVIRONMENT")
7
.unwrap_or_else(|_| "development".to_string());
8
9
// Load environment-specific file
10
let env_file = format!(".env.{}", environment);
11
dotenv::from_filename(&env_file).ok();
12
13
// Continue with setup
14
// ...
15
}

Multi-Environment Setup

Development Environment

1
# config/development.toml
2
3
[service]
4
name = "payment-service"
5
environment = "development"
6
7
[orchestrator]
8
url = "http://localhost:9090"
9
10
[worker]
11
port = 9080
12
concurrency = 5
13
14
[database]
15
url = "postgresql://postgres:postgres@localhost:5432/orcher_dev"
16
max_connections = 10
17
18
[logging]
19
level = "debug"
20
format = "pretty"
21
22
[metrics]
23
enabled = true
24
port = 9091

Run:

1
# Set environment
2
export ENVIRONMENT=development
3
4
# Run with dev config
5
cargo run --bin payment-service

Staging Environment

1
# config/staging.toml
2
3
[service]
4
name = "payment-service"
5
environment = "staging"
6
7
[orchestrator]
8
url = "https://orcher-staging.mycompany.com:9090"
9
10
[worker]
11
port = 9080
12
concurrency = 20
13
14
[database]
15
url = "postgresql://orcher_user:${DB_PASSWORD}@staging-db:5432/orcher_staging"
16
max_connections = 50
17
18
[logging]
19
level = "info"
20
format = "json"
21
file = "/var/log/orcher/service.log"
22
23
[metrics]
24
enabled = true
25
port = 9091

Deploy:

1
# Set environment
2
export ENVIRONMENT=staging
3
export DB_PASSWORD=staging_password
4
export ORCHER_AUTH_TOKEN=staging_token
5
6
# Run
7
./payment-service --config config/staging.toml

Production Environment

1
# config/production.toml
2
3
[service]
4
name = "payment-service"
5
environment = "production"
6
7
[orchestrator]
8
url = "https://orcher.mycompany.com:9090"
9
connect_timeout = "30s"
10
request_timeout = "60s"
11
12
[orchestrator.tls]
13
enabled = true
14
cert_path = "/etc/ssl/certs/orcher.crt"
15
key_path = "/etc/ssl/private/orcher.key"
16
ca_path = "/etc/ssl/certs/ca.crt"
17
18
[worker]
19
port = 9080
20
concurrency = 100
21
shutdown_timeout = "60s"
22
23
[database]
24
url = "postgresql://orcher_user:${DB_PASSWORD}@prod-db:5432/orcher_prod"
25
max_connections = 200
26
min_connections = 20
27
28
[logging]
29
level = "warn"
30
format = "json"
31
file = "/var/log/orcher/service.log"
32
33
[logging.remote]
34
enabled = true
35
endpoint = "https://logs.mycompany.com"
36
api_key_env = "LOGGING_API_KEY"
37
38
[metrics]
39
enabled = true
40
port = 9091
41
42
[metrics.prometheus]
43
enabled = true
44
push_gateway = "https://prometheus.mycompany.com"
45
46
[security]
47
auth_enabled = true
48
auth_token_env = "ORCHER_AUTH_TOKEN"
49
50
[security.rate_limit]
51
enabled = true
52
requests_per_second = 1000

Deploy with Docker:

1
# Dockerfile
2
FROM rust:1.70 as builder
3
WORKDIR /app
4
COPY . .
5
RUN cargo build --release
6
7
FROM debian:bullseye-slim
8
COPY --from=builder /app/target/release/payment-service /usr/local/bin/
9
COPY config/production.toml /etc/orcher/config.toml
10
11
# Install CA certificates
12
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
13
14
CMD ["payment-service", "--config", "/etc/orcher/config.toml"]

Docker Compose:

1
version: '3.8'
2
3
services:
4
payment-service:
5
build: .
6
environment:
7
- ENVIRONMENT=production
8
- 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/orcher
16
- ./certs:/etc/ssl/certs
17
restart: unless-stopped

Secrets Management

Using Environment Variables

1
use std::env;
2
3
#[tokio::main]
4
async fn main() -> orcher::Result<()> {
5
// Load secrets from environment
6
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 password
16
let database_url = format!(
17
"postgresql://orcher_user:{}@db:5432/orcher_prod",
18
db_password
19
);
20
21
// Secrets like `db_password` and `stripe_key` are used by your task
22
// implementations (which own the side effects); the worker itself only
23
// 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().await
33
}

Using HashiCorp Vault

1
use vaultrs::client::{VaultClient, VaultClientSettingsBuilder};
2
3
async fn load_secrets_from_vault() -> Result<Secrets> {
4
// Connect to Vault
5
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 secrets
13
let db_secret = client
14
.kv2("secret/orcher")
15
.read("database")
16
.await?;
17
18
let api_secret = client
19
.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
}
28
29
#[tokio::main]
30
async 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().await
39
}

Using AWS Secrets Manager

1
use aws_sdk_secretsmanager::Client;
2
3
async 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 credentials
8
let db_secret = client
9
.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 keys
19
let api_secret = client
20
.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.database
37
),
38
stripe_key: api_keys.stripe,
39
})
40
}

Configuration Validation

1
use orcher::config::Config;
2
use serde::Deserialize;
3
4
#[derive(Debug, Deserialize)]
5
struct 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
}
15
16
fn validate_url<'de, D>(deserializer: D) -> Result<String, D::Error>
17
where
18
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
}
25
26
fn validate_port<'de, D>(deserializer: D) -> Result<u16, D::Error>
27
where
28
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
}
36
37
fn validate_concurrency<'de, D>(deserializer: D) -> Result<usize, D::Error>
38
where
39
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
# .gitignore
2
.env
3
.env.*
4
!.env.example
5
config/**/secrets.toml
6
*.key
7
*.pem

2. Use Environment-Specific Configs

1
config/
2
├── base.toml # Shared configuration
3
├── development.toml # Dev overrides
4
├── staging.toml # Staging overrides
5
└── production.toml # Production overrides

3. Document Required Variables

1
# .env.example
2
# Copy to .env and fill in values
3
4
# Orchestrator Connection
5
ORCHER_ORCHESTRATOR_URL=http://localhost:9090
6
7
# Database
8
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/orcher_dev
9
10
# External Services (get from your dashboard)
11
STRIPE_API_KEY=sk_test_...
12
SENDGRID_API_KEY=SG...
13
14
# Optional: Monitoring
15
SENTRY_DSN=
16
DATADOG_API_KEY=

4. Validate Configuration on Startup

1
#[tokio::main]
2
async fn main() -> orcher::Result<()> {
3
// Load and validate config
4
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 startup
12
// ...
13
}

5. Use Type-Safe Configuration

1
use serde::Deserialize;
2
3
#[derive(Debug, Deserialize)]
4
struct AppConfig {
5
worker: WorkerConfig,
6
orchestrator: OrchestratorConfig,
7
database: DatabaseConfig,
8
}
9
10
impl 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 vars
19
config.apply_env_overrides()?;
20
21
Ok(config)
22
}
23
}

Troubleshooting

Configuration Not Loading

1
# Check file exists
2
ls -la orcher.toml
3
4
# Check file permissions
5
chmod 644 orcher.toml
6
7
# Verify TOML syntax
8
toml-check orcher.toml
9
10
# Enable debug logging
11
RUST_LOG=orcher::config=debug cargo run

Environment Variables Not Working

1
# Check variable is set
2
echo $ORCHER_ORCHESTRATOR_URL
3
4
# List all Orcher variables
5
env | grep ORCHER
6
7
# Source .env file manually
8
set -a && source .env && set +a

Database Connection Issues

1
# Test database connection
2
psql $DATABASE_URL -c "SELECT 1"
3
4
# Check connection string format
5
# postgresql://[user[:password]@][host][:port][/dbname][?param1=value1&...]
6
7
# Common issues:
8
# - Wrong password
9
# - Database doesn't exist
10
# - Host not reachable
11
# - Port blocked by firewall

Next Steps


Learn More

• CLI Reference - Complete CLI commands and options • Security Best Practices - Secure your configuration • Quickstart Repository - See configuration in action