Configuration

KalamDB loads runtime settings from server.toml and then applies KALAMDB_* environment overrides.

For complete section-by-section tuning, use Advanced Configuration.

Focused guides:

• OpenTelemetry (OTEL)
• OIDC & Issuer Trust
• Firebase
• MinIO (S3-Compatible)
• Keycloak
• Jaeger

Download Full Sample Config

• server.example.toml (full commented sample) 

1curl -L https://raw.githubusercontent.com/kalamstack/KalamDB/refs/heads/main/backend/server.example.toml -o server.example.toml

Run With Config File

1kalamdb-server --config /path/to/server.toml

Minimal Production-Oriented Example

1[server]2host = "0.0.0.0"3port = 29004api_version = "v1"5enable_http2 = true6 7[storage]8data_path = "./data"9 10[auth]11jwt_secret = "replace-with-strong-random-secret-32-plus-chars"12cookie_secure = true13allow_remote_setup = false14 15[rate_limit]16enable_connection_protection = true17max_requests_per_ip_per_sec = 20018max_auth_requests_per_ip_per_sec = 2019 20[topics]21visibility_timeout_secs = 6022 23[security]24max_request_body_size = 1048576025max_ws_message_size = 104857626 27[security.cors]28allowed_origins = ["https://app.example.com"]29allow_credentials = true

Notes:

• data_path is the canonical storage root key (not data_dir).
• auth can also be written as [authentication] (alias supported by config loader).
• table flush behavior is set per table via SQL WITH (FLUSH_POLICY = '...'), not a top-level storage.flush_policy key.
• topics.visibility_timeout_secs controls when unacknowledged topic consumer claims become available for redelivery.

High-Value Environment Overrides

These are commonly used in Docker and CI:

• KALAMDB_SERVER_HOST, KALAMDB_SERVER_PORT
• KALAMDB_DATA_DIR
• KALAMDB_LOG_LEVEL, KALAMDB_LOGS_DIR
• KALAMDB_JWT_SECRET, KALAMDB_JWT_TRUSTED_ISSUERS, KALAMDB_COOKIE_SECURE, KALAMDB_ALLOW_REMOTE_SETUP
• KALAMDB_RATE_LIMIT_AUTH_REQUESTS_PER_IP_PER_SEC
• KALAMDB_TOPIC_VISIBILITY_TIMEOUT_SECS
• KALAMDB_CLUSTER_ID, KALAMDB_NODE_ID, KALAMDB_CLUSTER_RPC_ADDR, KALAMDB_CLUSTER_API_ADDR, KALAMDB_CLUSTER_PEERS

Legacy vars like KALAMDB_HOST and KALAMDB_PORT are still recognized.

For OTEL-specific override behavior, see OpenTelemetry (OTEL). For IdP issuer setup, see OIDC & Issuer Trust.

Cluster Override Format

KALAMDB_CLUSTER_PEERS uses this format:

1node_id@rpc_addr@api_addr[@rpc_server_name];node_id@rpc_addr@api_addr[@rpc_server_name]

Example:

12@kalamdb-node2:2910@http://kalamdb-node2:2900;3@kalamdb-node3:2910@http://kalamdb-node3:2900