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:

Download Full Sample Config

server.example.toml (full commented sample)

BASH

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

Run With Config File

BASH

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

Minimal Production-Oriented Example

TOML

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[auth.local]16enabled = true17 18[rate_limit]19enable_connection_protection = true20max_requests_per_ip_per_sec = 20021max_auth_requests_per_ip_per_sec = 2022 23[topics]24visibility_timeout_secs = 6025 26[security]27max_request_body_size = 1048576028max_ws_message_size = 104857629 30[security.cors]31allowed_origins = ["https://app.example.com"]32allow_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.

Add OIDC To `server.toml`

KalamDB supports one external OIDC provider at a time.

TOML

1[auth]2jwt_trusted_issuers = "kalamdb,https://idp.example.com/realms/kalamdb"3 4[auth.local]5enabled = true6 7[auth.oidc]8enabled = true9display_name = "Company SSO"10issuer = "https://idp.example.com/realms/kalamdb"11client_id = "kalamdb"12scopes = ["openid", "email", "profile"]13auto_provision = true14default_role = "user"15broker_device_flow_enabled = true

Keep local auth enabled during bootstrap and rollout, then disable it later with [auth.local].enabled = false if you want an OIDC-only deployment.

High-Value Environment Overrides

These are commonly used in Docker and CI:

KALAMDB_SERVER_HOST, KALAMDB_SERVER_PORT, KALAMDB_SERVER_PUBLIC_ORIGIN, KALAMDB_SERVER_WORKERS
KALAMDB_DATA_DIR
KALAMDB_LOG_LEVEL, KALAMDB_LOG_FORMAT, KALAMDB_LOGS_DIR, KALAMDB_LOG_TO_CONSOLE
KALAMDB_JWT_SECRET, KALAMDB_JWT_TRUSTED_ISSUERS, KALAMDB_JWT_EXPIRY_HOURS, KALAMDB_COOKIE_SECURE, KALAMDB_ALLOW_REMOTE_SETUP
KALAMDB_AUTH_LOCAL_ENABLED
KALAMDB_AUTH_OIDC_ENABLED, KALAMDB_AUTH_OIDC_DISPLAY_NAME, KALAMDB_AUTH_OIDC_ISSUER, KALAMDB_AUTH_OIDC_CLIENT_ID, KALAMDB_AUTH_OIDC_CLIENT_SECRET
KALAMDB_AUTH_OIDC_SCOPES, KALAMDB_AUTH_OIDC_DEVICE_AUTHORIZATION_ENDPOINT, KALAMDB_AUTH_OIDC_BROKER_DEVICE_FLOW_ENABLED
KALAMDB_AUTH_OIDC_AUTO_PROVISION, KALAMDB_AUTH_OIDC_DEFAULT_ROLE, KALAMDB_AUTH_OIDC_AUDIENCE
KALAMDB_SECURITY_CORS_ALLOWED_ORIGINS, KALAMDB_SECURITY_TRUSTED_PROXY_RANGES
KALAMDB_RATE_LIMIT_AUTH_REQUESTS_PER_IP_PER_SEC
KALAMDB_TOPIC_VISIBILITY_TIMEOUT_SECS, KALAMDB_TOPIC_DEFAULT_RETENTION_SECONDS, KALAMDB_TOPIC_DEFAULT_RETENTION_MAX_BYTES
KALAMDB_CLUSTER_ID, KALAMDB_NODE_ID, KALAMDB_CLUSTER_RPC_ADDR, KALAMDB_CLUSTER_API_ADDR, KALAMDB_CLUSTER_PEERS
KALAMDB_RPC_TLS_ENABLED, KALAMDB_RPC_TLS_CA_CERT, KALAMDB_RPC_TLS_SERVER_CERT, KALAMDB_RPC_TLS_SERVER_KEY
KALAMDB_ROOT_PASSWORD for root bootstrap and KALAMDB_TOKIO_WORKER_THREADS for Tokio runtime sizing

Compatibility aliases still accepted today:

KALAMDB_CLUSTER_NODE_ID for KALAMDB_NODE_ID
KALAMDB_VISIBILITY_TIMEOUT_SECS for KALAMDB_TOPIC_VISIBILITY_TIMEOUT_SECS
KALAMDB_TRUSTED_PROXY_RANGES for KALAMDB_SECURITY_TRUSTED_PROXY_RANGES

For OTEL-specific override behavior, see OpenTelemetry (OTEL). For IdP issuer setup, see OIDC & Issuer Trust. For the full, complete override table, use Advanced Configuration.

Cluster Override Format

KALAMDB_CLUSTER_PEERS uses this format:

TEXT

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

Example: