Configuration and secrets

ConfigService loads application settings at startup and exposes an immutable view through DI. You do not need to create a new configuration owner for each request.

Local settings#

If bootstrap variables are not set, development mode reads lily.toml from the working directory. In this mode, a missing file allows schema defaults.

# lily.toml
[server]
host = "127.0.0.1"
port = 8080
tls_enabled = false
max_connections = 1000
request_timeout_secs = 30

[lifecycle]
shutdown_timeout_secs = 30

[custom]
application_name = "users-api"

AppBuilder::default() takes the listener address from configuration. AppBuilder::new("host:port") sets the address explicitly; it does not implicitly reset other settings or TLS.

Environment and secret precedence#

Values are prepared in this order:

1. The TOML file is read.
2. LILY__SECTION__FIELD environment values are applied.
3. Exact ${secret:key} and ${file:/absolute/path} references are resolved.
4. The typed schema is validated and an immutable snapshot is created.

For example, LILY__SERVER__PORT=9090 changes the port. Unknown typed fields are rejected; keep application-specific keys under [custom].

Production startup#

Provide the path and mode together. A missing configuration file is an error in production.

LILY_CONFIG_PATH=/etc/lily/lily.toml LILY_CONFIG_MODE=production cargo run

AppBuilder::secret_resolver(resolver) connects your application's secret resolver before configuration is loaded. It cannot be used together with .container(...). When building an external container, seed the registered Singleton with ConfigService::with_options_and_secret_resolver(...).

Read settings and apply overrides#

Services read application values with ConfigService::get, get_optional, and get_or_default. Use redacted_effective_config for an operational view. There is no runtime reload; changes apply on the next startup.

transport_config, rustls_config, and tls_disabled are the relevant builder overrides. Not every transport field exists in the TOML server schema. Use HttpTransportConfig for fields such as max_request_body_bytes and trusted_proxy_cidrs.