Saga Configuration

Saga can be configured via environment variables, configuration files, or default values. Understanding the configuration precedence and options is essential for proper deployment.

Configuration Precedence

Configuration values follow this order (highest to lowest precedence):

1. Environment variables (override everything)
2. Config file (~/.saga/config.toml or custom path)
3. Default values (lowest precedence)

Configuration Methods

Environment Variables

Environment variables provide the highest precedence and are ideal for containerized deployments.

export REDIS_URL=redis://localhost:6379
export PORT=8030
export HOST=0.0.0.0
cargo run

Advantages:

• ✅ Highest precedence
• ✅ Easy to override in different environments
• ✅ Works well with Docker/Kubernetes
• ✅ No file management needed

Config File

Configuration files are convenient for local development and consistent settings.

Location: ~/.saga/config.toml

redis_url = "redis://localhost:6379"
host = "0.0.0.0"
port = 8030
service_name = "saga"
heartbeat_interval = 30
registration_ttl = 60

Advantages:

• ✅ Persistent settings
• ✅ Version control friendly
• ✅ Easy to share across team
• ✅ Can be overridden by environment variables

Default Values

If no configuration is provided, Saga uses sensible defaults.

// Default values
host: "0.0.0.0"
port: 8030
service_name: "saga"
heartbeat_interval: 30
registration_ttl: 60

Note: REDIS_URL has no default and must be provided.

Environment Variables Reference

Required Variables

Variable	Description	Example	Notes
REDIS_URL	Redis connection URL	redis://localhost:6379	Required - No default value

Missing REDIS_URL

If REDIS_URL is not set, Saga will fail to start. Always ensure this variable is configured.

Optional Variables

Variable	Description	Default	Example	Notes
HOST	HTTP server host	0.0.0.0	0.0.0.0	Bind to all interfaces
PORT	HTTP server port	8030	8030	Must be available
SERVICE_NAME	Service name	saga	saga	Used in health checks
HEARTBEAT_INTERVAL	Heartbeat interval (seconds)	30	30	How often to refresh TTL
REGISTRATION_TTL	Registration TTL (seconds)	60	60	Service expiration time

TTL vs Heartbeat Interval

Set HEARTBEAT_INTERVAL to approximately half of REGISTRATION_TTL to ensure reliable service availability:

• TTL: 60 seconds
• Heartbeat: 30 seconds (50% of TTL)
• Safety margin: 30 seconds buffer for network delays

Configuration File Format

Saga uses TOML format for configuration files. The default location is ~/.saga/config.toml.

Example Config File

Create ~/.saga/config.toml:

# Redis Configuration
redis_url = "redis://localhost:6379"

# Server Configuration
host = "0.0.0.0"
port = 8030

# Service Configuration
service_name = "saga"

# Registration Settings
heartbeat_interval = 30  # seconds
registration_ttl = 60     # seconds

Custom Config File Path

Specify a custom config file using the --config flag:

cargo run -- --config /path/to/custom/config.toml

Or set via environment:

export SAGA_CONFIG=/path/to/custom/config.toml
cargo run

Redis Configuration

Local Development

Docker

# Using Docker Compose
REDIS_URL=redis://redis:6379

# Using standalone Docker
REDIS_URL=redis://localhost:6379

Local Installation

# Default Redis installation
REDIS_URL=redis://localhost:6379

# Custom port
REDIS_URL=redis://localhost:6380

Remote Redis

# Remote Redis server
REDIS_URL=redis://redis.example.com:6379

# With authentication
REDIS_URL=redis://:password@redis.example.com:6379

# With username and password
REDIS_URL=redis://username:password@redis.example.com:6379

Redis Connection String Format

redis://[username][:password]@host[:port][/database]

Examples:

# Basic connection
redis://localhost:6379

# With password
redis://:mypassword@localhost:6379

# With username and password
redis://user:pass@localhost:6379

# With database selection
redis://localhost:6379/0

# Full example
redis://user:pass@redis.example.com:6379/0

Redis Authentication

If your Redis instance requires authentication, include credentials in the URL:

REDIS_URL=redis://:yourpassword@localhost:6379

For username + password:

REDIS_URL=redis://username:password@localhost:6379

Production Configuration

Recommended Settings

For production environments, use these recommended values:

# Redis (use Redis Cluster or Sentinel for HA)
REDIS_URL=redis://redis-cluster:6379

# Server
HOST=0.0.0.0
PORT=8030

# Service
SERVICE_NAME=saga

# Registration (longer TTL for production)
HEARTBEAT_INTERVAL=30
REGISTRATION_TTL=120  # 2 minutes for production

High Availability Setup

For high availability configurations:

Redis Sentinel

# Redis Sentinel configuration
REDIS_URL=redis-sentinel://sentinel1:26379,sentinel2:26379,sentinel3:26379/mymaster

Benefits:

• ✅ Automatic failover
• ✅ High availability
• ✅ No single point of failure

Redis Cluster

# Redis Cluster configuration
REDIS_URL=redis-cluster://node1:6379,node2:6379,node3:6379

Benefits:

• ✅ Horizontal scaling
• ✅ Sharding across nodes
• ✅ High throughput

Production TTL Settings

For production, increase REGISTRATION_TTL to account for:

• Network partitions
• Temporary service restarts
• Load balancer health checks

Recommended:

• TTL: 120 seconds (2 minutes)
• Heartbeat: 30 seconds
• Safety margin: 90 seconds buffer

Configuration Examples

Development Environment

# .env file for development
REDIS_URL=redis://localhost:6379
PORT=8030
HOST=0.0.0.0
REGISTRATION_TTL=60
HEARTBEAT_INTERVAL=30

Usage:

# Load from .env file
source .env
cargo run

# Or use dotenvy
dotenvy::dotenv().ok();

Production Environment

# Production environment variables
export REDIS_URL=redis://redis-cluster:6379
export PORT=8030
export HOST=0.0.0.0
export REGISTRATION_TTL=120
export HEARTBEAT_INTERVAL=30
export SERVICE_NAME=saga

Docker Compose

services:
  saga:
    image: saga:latest
    environment:
      - REDIS_URL=redis://redis:6379
      - PORT=8030
      - HOST=0.0.0.0
      - REGISTRATION_TTL=120
      - HEARTBEAT_INTERVAL=30
    ports:
      - "8030:8030"
    depends_on:
      - redis

Kubernetes ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: saga-config
data:
  HOST: "0.0.0.0"
  PORT: "8030"
  SERVICE_NAME: "saga"
  HEARTBEAT_INTERVAL: "30"
  REGISTRATION_TTL: "120"
---
apiVersion: v1
kind: Secret
metadata:
  name: saga-secrets
data:
  REDIS_URL: <base64-encoded-redis-url>

Configuration Validation

Saga validates all configuration values on startup:

Validation Rules

Variable	Validation	Error Message
REDIS_URL	Must be valid Redis URL	"Invalid Redis URL format"
PORT	Must be 1-65535	"Port must be between 1 and 65535"
HEARTBEAT_INTERVAL	Must be > 0	"Heartbeat interval must be greater than 0"
REGISTRATION_TTL	Must be > 0	"Registration TTL must be greater than 0"

Validation Example

# Invalid port (too high)
export PORT=99999
cargo run
# Error: Port must be between 1 and 65535

# Invalid TTL (zero)
export REGISTRATION_TTL=0
cargo run
# Error: Registration TTL must be greater than 0

Troubleshooting Configuration

Redis Connection Issues

Check Connection

# Test Redis connection
redis-cli -u $REDIS_URL ping

# Should return: PONG

Debug Mode

# Enable debug logging
RUST_LOG=saga=debug cargo run

# Look for Redis connection messages
# Should see: "Connected to Redis successfully"

Port Already in Use

# Find process using port
lsof -i :8030

# Kill the process
kill -9 <PID>

# Or use different port
export PORT=8031
cargo run

Configuration Not Loading

# Check config file exists
ls -la ~/.saga/config.toml

# Validate TOML syntax
toml-cli validate ~/.saga/config.toml

# Use verbose logging
RUST_LOG=saga=debug cargo run

Best Practices

Configuration Best Practices

1. Use environment variables in production - More secure and flexible
2. Use config files for development - Easier to manage locally
3. Never commit secrets - Use environment variables or secrets management
4. Validate before deployment - Test configuration in staging first
5. Document your settings - Keep a record of production configuration

Next Steps

• Review Deployment Guide for production configuration
• Check Troubleshooting for configuration issues
• See Integration Examples for configuration in code