Skip to main content
iii uses a YAML configuration file to define modules and their settings. The engine supports environment variable expansion, making it easy to configure for different environments.

​
Configuration File

By default, iii looks for config.yaml in the current directory. You can specify a different path: 
iii --config /path/to/config.yaml
If no config file is found, iii loads default modules: HTTP, Queue, Cron, Stream, and Observability.

​
Environment Variable Expansion

Config files support environment variable expansion with default values: 
${VARIABLE_NAME:default_value}
Examples: 
modules:
  - class: modules::stream::StreamModule
    config:
      port: ${STREAM_PORT:3112}
      host: ${STREAM_HOST:127.0.0.1}
      adapter:
        class: modules::stream::adapters::RedisAdapter
        config:
          redis_url: ${REDIS_URL:redis://localhost:6379}
If STREAM_PORT is not set, it defaults to 3112. If a variable has no default and is not set, the engine will panic with an error.

​
Module Configuration

​
Basic Structure

Each module entry requires a class and optional config: 
modules:
  - class: modules::api::RestApiModule
    config:
      port: 3111
      host: 127.0.0.1

​
REST API Module

Configures the HTTP server for API endpoints. 
- class: modules::api::RestApiModule
  config:
    port: 3111
    host: 127.0.0.1
    default_timeout: 30000
    concurrency_request_limit: 1024
    cors:
      allowed_origins:
        - '*'
      allowed_methods:
        - GET
        - POST
        - PUT
        - DELETE
        - OPTIONS
​
port
number
default:"3111"
HTTP server port
​
host
string
default:"127.0.0.1"
Bind address (use 0.0.0.0 for all interfaces)
​
default_timeout
number
default:"30000"
Default request timeout in milliseconds
​
concurrency_request_limit
number
default:"1024"
Maximum concurrent requests

​
Stream Module

Real-time WebSocket state synchronization. 
- class: modules::stream::StreamModule
  config:
    port: ${STREAM_PORT:3112}
    host: 127.0.0.1
    adapter:
      class: modules::stream::adapters::RedisAdapter
      config:
        redis_url: redis://localhost:6379
Alternative: File-based adapter 
adapter:
  class: modules::stream::adapters::KvStore
  config:
    store_method: file_based  # Options: in_memory, file_based
    file_path: ./data/stream_store

​
Queue Module

Redis-backed message queue for async job processing. 
- class: modules::queue::QueueModule
  config:
    adapter:
      class: modules::queue::RedisAdapter
      config:
        redis_url: redis://localhost:6379

​
State Module

Persistent key-value storage for application state. 
- class: modules::state::StateModule
  config:
    adapter:
      class: modules::state::adapters::KvStore
      config:
        store_method: file_based
        file_path: ./data/state_store.db

​
KV Server

Internal key-value server for coordination. 
- class: modules::kv_server::KvServer
  config:
    store_method: file_based  # Options: in_memory, file_based
    file_path: ./data/kv_store
    save_interval_ms: 5000

​
Observability Module

OpenTelemetry traces, metrics, and logs. 
- class: modules::observability::OtelModule
  config:
    enabled: ${OTEL_ENABLED:true}
    service_name: ${OTEL_SERVICE_NAME:iii}
    service_version: ${SERVICE_VERSION:0.2.0}
    service_namespace: ${SERVICE_NAMESPACE:production}
    
    # Exporter: "otlp", "memory", or "both"
    exporter: ${OTEL_EXPORTER_TYPE:memory}
    endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:http://localhost:4317}
    
    # Sampling
    sampling_ratio: 1.0
    
    # Metrics
    metrics_enabled: true
    metrics_exporter: ${OTEL_METRICS_EXPORTER:memory}
    metrics_retention_seconds: 3600
    metrics_max_count: 10000
    
    # Logs
    logs_enabled: ${OTEL_LOGS_ENABLED:true}
    logs_exporter: ${OTEL_LOGS_EXPORTER:memory}
    logs_max_count: ${OTEL_LOGS_MAX_COUNT:1000}
    logs_retention_seconds: ${OTEL_LOGS_RETENTION_SECONDS:3600}
    logs_sampling_ratio: ${OTEL_LOGS_SAMPLING_RATIO:1.0}
    logs_console_output: ${OTEL_LOGS_CONSOLE_OUTPUT:true}
​
exporter
string
default:"memory"
Trace exporter: otlp (remote collector), memory (in-memory), or both
​
sampling_ratio
number
default:"1.0"
Sampling ratio (0.0 to 1.0). Use 1.0 to sample all traces.

​
Cron Module

Distributed cron scheduling. 
- class: modules::cron::CronModule
  config:
    adapter:
      class: modules::cron::KvCronAdapter

​
PubSub Module

Publish-subscribe messaging. 
- class: modules::pubsub::PubSubModule
  config:
    adapter:
      class: modules::pubsub::LocalAdapter

​
Minimal Configuration

For development without Redis: 
modules:
  - class: modules::api::RestApiModule
    config:
      host: 127.0.0.1
      port: 3111
      
  - class: modules::observability::OtelModule
    config:
      enabled: false

​
Environment Variables

Common environment variables:
VariableDefaultDescription
STREAM_PORT3112Stream WebSocket port
REDIS_URLredis://localhost:6379Redis connection URL
OTEL_ENABLEDtrueEnable OpenTelemetry
OTEL_SERVICE_NAMEiiiService name for telemetry
SERVICE_VERSION0.2.0Service version
SERVICE_NAMESPACEproductionEnvironment namespace
OTEL_EXPORTER_TYPEmemoryTrace exporter type
RUST_LOG-Logging level (info, debug, trace)
Set environment variables before starting iii: 
export REDIS_URL=redis://prod-redis:6379
export OTEL_ENABLED=true
export OTEL_EXPORTER_TYPE=otlp
export RUST_LOG=info
iii --config config.yaml

​
Production Configuration

For production deployments: 
modules:
  - class: modules::api::RestApiModule
    config:
      host: 0.0.0.0  # Bind to all interfaces
      port: 3111
      default_timeout: 30000
      concurrency_request_limit: 2048
      cors:
        allowed_origins:
          - https://app.example.com
        allowed_methods:
          - GET
          - POST
          - PUT
          - DELETE

  - class: modules::stream::StreamModule
    config:
      port: 3112
      host: 0.0.0.0
      adapter:
        class: modules::stream::adapters::RedisAdapter
        config:
          redis_url: ${REDIS_URL:redis://redis:6379}

  - class: modules::queue::QueueModule
    config:
      adapter:
        class: modules::queue::RedisAdapter
        config:
          redis_url: ${REDIS_URL:redis://redis:6379}

  - class: modules::state::StateModule
    config:
      adapter:
        class: modules::state::adapters::KvStore
        config:
          store_method: file_based
          file_path: /data/state_store.db

  - class: modules::kv_server::KvServer
    config:
      store_method: file_based
      file_path: /data/kv_store
      save_interval_ms: 5000

  - class: modules::observability::OtelModule
    config:
      enabled: true
      service_name: iii-production
      service_version: ${SERVICE_VERSION:0.2.0}
      service_namespace: production
      exporter: otlp
      endpoint: ${OTEL_ENDPOINT:http://otel-collector:4317}
      sampling_ratio: 0.1  # 10% sampling in production
      metrics_enabled: true
      logs_enabled: true

  - class: modules::cron::CronModule
    config:
      adapter:
        class: modules::cron::KvCronAdapter

  - class: modules::pubsub::PubSubModule
    config:
      adapter:
        class: modules::pubsub::LocalAdapter

​
Next Steps

Docker Deployment

Run iii in containers

Production Setup

Hardened production deployment

Build docs developers (and LLMs) love

Get started for freeTalk to us