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
• MinIO (S3-Compatible)
• Keycloak
• Jaeger

Download Full Sample Config

• server.example.toml (full commented sample) 

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

Run With Config File

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

Minimal Production-Oriented Example

[server]
host = "0.0.0.0"
port = 8080
api_version = "v1"
enable_http2 = true
 
[storage]
data_path = "./data"
 
[auth]
jwt_secret = "replace-with-strong-random-secret-32-plus-chars"
cookie_secure = true
allow_remote_setup = false
 
[rate_limit]
enable_connection_protection = true
max_requests_per_ip_per_sec = 200
max_auth_requests_per_ip_per_sec = 20
 
[security]
max_request_body_size = 10485760
max_ws_message_size = 1048576
 
[security.cors]
allowed_origins = ["https://app.example.com"]
allow_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.

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_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:

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

Example:

2@kalamdb-node2:9090@http://kalamdb-node2:8080;3@kalamdb-node3:9090@http://kalamdb-node3:8080