Configuration reference

Keys live under [riverbase] in riverbase.toml (or at the file root). Environment variables win over the file. See Configuration for loading rules.

Service

Key	Env	Default	Meaning
db_url	RIVERBASE_DB_URL, DB_URL	placeholder	Postgres DSN
bind_addr	RIVERBASE_BIND_ADDR	0.0.0.0:8080	Listen address
api_base	RIVERBASE_API_BASE	/api	Prefix for every framework route
api_zone	RIVERBASE_API_ZONE (comma-separated)	[]	Register only routes allowed in these zones
service_mode	RIVERBASE_SERVICE_MODE	coupled	coupled or split (informational)
deny_unknown_fields	RIVERBASE_DENY_UNKNOWN_FIELDS	false	Reject undeclared command payload properties
request_body_max_bytes	RIVERBASE_REQUEST_BODY_MAX_BYTES	262144 (256 KiB)	JSON body limit
request_upload_max_bytes	RIVERBASE_REQUEST_UPLOAD_MAX_BYTES	20971520 (20 MiB)	Multipart upload limit
rtc_wire_encoding	RIVERBASE_RTC_WIRE_ENCODING	json	Default WebSocket codec

The split example binaries read RIVERBASE_COMMAND_BIND_ADDR (default :8081) and RIVERBASE_QUERY_BIND_ADDR (default :8082) themselves; follow the same pattern in your own split binaries.

Logging

Key	Env	Default	Meaning
log_level	RIVERBASE_LOG_LEVEL	info	Tracing filter; RUST_LOG overrides
log_format	RIVERBASE_LOG_FORMAT	compact	compact, pretty, or json
log_http_requests	RIVERBASE_LOG_HTTP_REQUESTS	false	One line per request

Database pool and queries

Key	Env	Default
dbpool_max_size	RIVERBASE_DBPOOL_MAX_SIZE	32 (clamped 1–128)
dbpool_acquire_timeout_secs	RIVERBASE_DBPOOL_ACQUIRE_TIMEOUT_SECS	30
dbpool_max_lifetime_secs	RIVERBASE_DBPOOL_MAX_LIFETIME_SECS	1800
database_statement_timeout_ms	RIVERBASE_DATABASE_STATEMENT_TIMEOUT_MS	60000
query_max_limit		500 (largest page size)
query_count_max_rows		10000 (cap for exact counts)

Tenancy

Key	Env	Default	Meaning
tenant	RIVERBASE_TENANT (alias RIVERBASE_REALM)	empty	Deployment tenant: a UUID, or a name hashed to a UUID
tenant_access_policy	RIVERBASE_TENANT_ACCESS_POLICY	profile-organization	Who may see which _tenant
tenant_stamp_policy	RIVERBASE_TENANT_STAMP_POLICY	profile-organization	What new rows are stamped with

See Multi-tenancy.

[riverbase.audit_log]

Key	Env	Default
context	RIVERBASE_AUDIT_LOG_CONTEXT	true
command	RIVERBASE_AUDIT_LOG_COMMAND	true
event	RIVERBASE_AUDIT_LOG_EVENT	true
message	RIVERBASE_AUDIT_LOG_MESSAGE	true
activity	RIVERBASE_AUDIT_LOG_ACTIVITY	true
response	RIVERBASE_AUDIT_LOG_RESPONSE	true
query	RIVERBASE_AUDIT_LOG_QUERY	false
idempotency		true

[riverbase.bus]

Key	Env	Default
url	RIVERBASE_BUS_URL, BUS_URL	nats://127.0.0.1:4222
kind		inferred from the URL scheme (nats, redis, postgres)

[riverbase.auth]

Key	Env	Meaning
auth_provider	RIVERBASE_AUTH_PROVIDER	None, MockAuth, or Keycloak (oidc)
issuer	RIVERBASE_AUTH_ISSUER, RIVERBASE_OIDC_ISSUER	Token issuer
audience	RIVERBASE_OIDC_AUDIENCE	Expected aud
accepted_azp		Accepted authorized parties; must be non-empty in production
jwks_ttl_secs, leeway_secs, http_timeout_secs		JWKS caching and clock tolerance
keycloak_base_url, keycloak_realm	RIVERBASE_AUTH_KEYCLOAK_REALM	Keycloak location
oauth2_client_id, oauth2_client_secret	RIVERBASE_AUTH_OAUTH2_CLIENT_ID, RIVERBASE_AUTH_OAUTH2_CLIENT_SECRET	OAuth2 client
application_secret_key		Session signing key; no default
session_cookie, cookie_https_only, cookie_same_site, validate_csrf_token		Cookie and CSRF settings
default_callback_uri, default_signin_redirect_uri, default_logout_redirect_uri, safe_redirect_domains		Redirects
create_initial_profile	RIVERBASE_AUTH_CREATE_INITIAL_PROFILE	Create a profile on first sign-in
require_realm_role		Realm role a user must have
mock_*, [[riverbase.auth.mock_users]]		MockAuth identities

RIVERBASE_AUTH_ENABLED and RIVERBASE_AUTH_DISABLED=1 switch auth explicitly. RIVERBASE_OIDC_DISCOVERY_URL overrides OIDC discovery.

[riverbase.casbin]

Key	Env	Default
enabled	RIVERBASE_CASBIN_ENABLED	false
omit_inaccessible_openapi	RIVERBASE_CASBIN_OMIT_INACCESSIBLE_OPENAPI	false
model		empty: the framework default model
policy		empty: deny everything

[riverbase.media]

Key	Env
protocol	RIVERBASE_MEDIA_PROTOCOL (fs, s3, http)
fs_root	RIVERBASE_MEDIA_FS_ROOT
fskey	RIVERBASE_MEDIA_FSKEY
root_path	RIVERBASE_MEDIA_ROOT_PATH
params.bucket, params.region, params.endpoint	RIVERBASE_MEDIA_BUCKET, RIVERBASE_MEDIA_REGION, RIVERBASE_MEDIA_ENDPOINT
access keys	RIVERBASE_MEDIA_ACCESS_KEY_ID, RIVERBASE_MEDIA_SECRET_ACCESS_KEY
virtual-host-style S3 addressing	RIVERBASE_MEDIA_ENABLE_VIRTUAL_HOST_STYLE

Signed tokens

Section	Env
[riverbase.link_token]	RIVERBASE_LINK_TOKEN_SECRET, RIVERBASE_LINK_TOKEN_SALT
[riverbase.hook_token]	RIVERBASE_HOOK_TOKEN_SECRET, RIVERBASE_HOOK_TOKEN_SALT

Process-level variables

Env	Meaning
RIVERBASE_CONFIG	Path to the config file
RIVERBASE_CONFIG_URI, RIVERBASE_CONFIG_FORMAT, RIVERBASE_CONFIG_SOPS	Remote config (cfgfetch features)
RIVERBASE_CONFIG_HTTP_TOKEN, RIVERBASE_CONFIG_GIT_TOKEN, RIVERBASE_CONFIG_GIT_RAW_TEMPLATE, RIVERBASE_CONFIG_OCI_TOKEN	Remote config credentials
RIVERBASE_DEBUG	Verbosity only
RIVERBASE_INSECURE_ALLOW	Comma-separated startup checks to waive
RIVERBASE_FORM_DB_URL	Dedicated database for riverbase_form