Configuration

Every service reads one RiverbaseConfig. Values come from three layers, and later layers win:

1. Defaults compiled into the framework.
2. TOML file: the [riverbase] table of riverbase.toml.
3. Environment: RIVERBASE_* variables.

RiverbaseApp::init loads the configuration for you. Read it back with app.config().

Where the file is found

The loader checks, in order:

1. the path in RIVERBASE_CONFIG;
2. ./riverbase.toml;
3. ./config/riverbase.toml.

Keys can sit under a [riverbase] table or at the root of the file.

A typical service file

service/riverbase.toml

[riverbase]
db_url = "postgresql://USER:PASSWORD@127.0.0.1:5432/riverbase"
bind_addr = "0.0.0.0:8080"
log_level = "info"
log_format = "compact"          # compact | pretty | json
service_mode = "coupled"        # coupled | split
api_zone = ["default"]

[riverbase.bus]
# nats:// (production default), redis://, or postgres:// for LISTEN/NOTIFY
url = "postgresql://USER:PASSWORD@127.0.0.1:5432/riverbase"

[riverbase.audit_log]
command = true
event = true
message = true
activity = true
response = true
query = false

Keep secrets out of the file

Commit placeholders only. Set RIVERBASE_DB_URL (and any auth secrets) in the environment, or load them from a secrets manager with remote config.

The settings you will touch first

Key	Env	Default	Purpose
db_url	RIVERBASE_DB_URL (or DB_URL)	local placeholder	Postgres DSN for state, audit, and framework tables
bind_addr	RIVERBASE_BIND_ADDR	0.0.0.0:8080	Listen address
api_base	RIVERBASE_API_BASE	/api	Prefix for domain, auth, OpenAPI, and RxDB routes
log_level	RIVERBASE_LOG_LEVEL	info	Tracing filter (RUST_LOG overrides)
log_format	RIVERBASE_LOG_FORMAT	compact	compact, pretty, or json
service_mode	RIVERBASE_SERVICE_MODE	coupled	Informational: coupled or split
bus.url	RIVERBASE_BUS_URL (or BUS_URL)	nats://127.0.0.1:4222	Message bus for integration messages
api_zone	RIVERBASE_API_ZONE	empty	Only register routes whose zones intersect this list

Every key, including auth, Casbin, media, tenancy, pool, and request limits, is listed in the Configuration reference.

Sections

Section	Configures	Page
[riverbase.audit_log]	Which audit channels persist	Audit log
[riverbase.bus]	NATS, Redis, or Postgres message bus	Transport
[riverbase.auth]	MockAuth or Keycloak/OIDC, sessions, cookies	Authentication
[riverbase.casbin]	Activity authorization model and policy	Authorization
[riverbase.media]	File storage backend	riverbase_file
[riverbase.link_token], [riverbase.hook_token]	Signed :link and :hook command URLs	HTTP conventions

Development switches

Variable	Effect
RIVERBASE_DEBUG=1	More verbose diagnostics. It does not relax any security check.
RIVERBASE_INSECURE_ALLOW=check1,check2	Explicitly waive named startup security checks. Use it in throwaway environments only.
RIVERBASE_AUTH_DISABLED=1	Run without an auth provider.

See Secure defaults for the checks a production service must pass.

Remote configuration

With the cfgfetch feature family, riverbase_core can fetch the configuration document from HTTPS, git, S3, or an OCI registry, optionally SOPS-encrypted, and keep it in memory:

cargo add riverbase_core --git https://github.com/riverbase-io/riverbase --features cfgfetch-https
export RIVERBASE_CONFIG_URI=https://config.example.com/services/todo.toml
export RIVERBASE_CONFIG_HTTP_TOKEN=…

Related variables: RIVERBASE_CONFIG_FORMAT, RIVERBASE_CONFIG_SOPS, RIVERBASE_CONFIG_GIT_TOKEN, RIVERBASE_CONFIG_OCI_TOKEN.

Reading config in your code

let app = RiverbaseApp::init("Todo Service", "Coupled command and query API")?;
let cfg = app.config();
tracing::info!(bind = %cfg.bind_addr, zones = ?cfg.api_zone, "starting");

Outside a web service, for example in a worker or CLI, call RiverbaseConfig::load() directly.