Overview
Configuration Reference
Format: HOCON (Human-Optimized Config Object Notation)
Override Priority
Section titled “Override Priority”Settings are resolved in this order (highest to lowest):
- CLI flags (
-r,--readonly,--config, etc.) - System properties (
-Dkey=valueor-DKEY=VALUE) - SCRIBE_* env vars (
SCRIBE_LDAP_URL,SCRIBE_DATABASE_PASSWORD, etc.) - Standard env vars (
OTEL_*,POSTGRES_*, etc. where supported) - This config file (values defined below)
- Built-in defaults
Environment Variables
Section titled “Environment Variables”SCRIBE_* variables follow the config path with dots → underscores. Some frequently-tuned settings have shorter aliases.
| Config path | Environment variable |
|---|---|
log.level | SCRIBE_LOG_LEVEL |
concurrency | SCRIBE_CONCURRENCY |
ldap.url | SCRIBE_LDAP_URL |
ldap.max-size-limit | SCRIBE_LDAP_MAX_SIZE_LIMIT |
monitoring.hints.enabled | SCRIBE_HINTS_ENABLED (alias) |
database.url | SCRIBE_DATABASE_URL |
database.password | SCRIBE_DATABASE_PASSWORD |
database.max-pool-size | SCRIBE_DATABASE_MAX_POOL_SIZE |
monitoring.prometheus.enabled | SCRIBE_PROMETHEUS_ENABLED (alias) |
monitoring.traces.enabled | SCRIBE_TRACES_ENABLED |
The ${?VAR} syntax substitutes VAR if defined, otherwise keeps the previous value. When multiple assignments exist, the last one wins.
Value Formats
Section titled “Value Formats”| Type | Examples |
|---|---|
| Booleans | true, false, yes, no, on, off |
| Durations | 500ms, 5s, 30m, 1h, 2d |
| Sizes | 1k, 2m, 3g (bytes) |
| Numbers | 42, 3.14 (no quotes) |
| Strings | "quoted" or unquoted-simple |
Substitution Behavior
Section titled “Substitution Behavior”When ${?VAR} is used WITHOUT a preceding default, the key is undefined if VAR is not set. This allows runtime overrides to fill in values.
When a concrete default precedes ${?VAR}, that default “pins” the value:
key = "default" # Key is always definedkey = ${?SCRIBE_KEY} # Only overrides if SCRIBE_KEY is setAdvanced: CONFIG_FORCE_*
Section titled “Advanced: CONFIG_FORCE_*”With -Dconfig.override_with_env_vars=true, any config key can be overridden using CONFIG_FORCE_* environment variables:
CONFIG_FORCE_a_b__c___d→ config keya.b-c_d- Name mangling:
_→.,__→-,___→_
Config File Location
Section titled “Config File Location”The application searches for the config file in order:
- CLI:
--config /path/to/identity-scribe.conf - System property:
-Dconfig.file=... - Env var:
SCRIBE_CONFIG_FILE(preferred) - Env var:
CONFIG_FILE(fallback) - CWD:
identity-scribe.conf - CWD:
config/identity-scribe.conf - Next to binary:
./identity-scribe.conf - Next to binary:
./config/identity-scribe.conf
Configuration Inheritance
Section titled “Configuration Inheritance”Some sections support automatic inheritance:
http {}→http.sockets.<name> {}ssl {}→ldap.ssl {},http.ssl {}
For inheritable sections, just override what differs:
http.sockets.internal { port = 9001 concurrency-limit.max-limit = 50}