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`

Service​

Logging​

Database pool and queries​

Tenancy​

[riverbase.audit_log]​

[riverbase.bus]​

[riverbase.auth]​

[riverbase.casbin]​

[riverbase.media]​

Signed tokens​

Process-level variables​