Configuration
- Choose a template
Evaluation, recommended defaults or production.
- Set your values
Database, directory and credentials.
- Verify
Start Scribe and check the resolved behavior.
You will know where to put a setting and which value takes precedence.
You decide: Choose a starter template before adding individual settings.
Next: Attribute modeling
IdentityScribe uses HOCON files, environment variables, and CLI flags. You only need to set what differs from the defaults — everything else comes from reference.conf.
For schema decisions such as which values to sync as plain attributes and which relationship views to compute at query time, start with Attribute Modeling.
Configuration priority
Section titled “Configuration priority”| Priority | Source | Example |
|---|---|---|
| 1 | CLI flags | -r, --readonly, --config /path/to/config |
| 2 | System properties | -Dreadonly=true, -DSCRIBE_LDAP_URL=ldap://... |
| 3 | SCRIBE_* env vars | SCRIBE_LDAP_URL, SCRIBE_DATABASE_PASSWORD |
| 4 | Declared aliases | OTEL_*, LDAP_*, MONITORING_*, and documented bare aliases |
| 5 | Config file | Values in identity-scribe.conf |
| 6 | Defaults | Built-in fallbacks in reference.conf |
Every environment variable declared in the configuration reference overrides the file,
in the alias order each setting documents: SCRIBE_LDAP_SO_TIMEOUT wins over LDAP_SO_TIMEOUT, which wins over SO_TIMEOUT.
An empty or blank variable counts as unset.
An environment value replaces the whole setting, including an object, a list, or a set of export headers.
List settings keep the string form documented for each setting, for example SCRIBE_AUTH_METHODS=bearer,ldap
or a space-separated SCRIBE_LDAP_SINGLE_VALUE_ATTRIBUTES="cn uid ou".
Object settings take a self-contained HOCON object, such as SCRIBE_LDAP_VIRTUAL_ATTRIBUTES='{}';
includes and external substitutions are not supported inside it. A value that is not such an object prevents
startup with an error that names the setting but not the value. The contents of a valid object are checked as
they are in the configuration file, and those errors can include the value, such as an invalid filter.
All other environment values remain literal strings. Passwords are untouched, and numbers,
booleans and durations keep their usual conversion. Each setting validates these values as it does
for a value in the configuration file.
SCRIBE_LICENSE_FILE and the POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER and POSTGRES_PASSWORD
fallbacks are exceptions: they apply only when the configuration file does not set license.file or the
matching database setting.
Since v3.3.0, startup emits one config_env_override warning listing settings where an environment variable
replaced a different explicit file value. The warning never includes values. Defaults and settings
controlled by a higher-priority flag or system property do not trigger it. Values are compared as written,
list items one by one, so an equivalent value written differently, such as cn sn for [cn, sn],
may still be reported as an override.
Before upgrading, review the variables in the service unit, container definition, and shell profile.
Remove stale variables so they cannot override the intended configuration.
Starter templates
Section titled “Starter templates”IdentityScribe ships three config templates. Copy one to identity-scribe.conf and edit it for your environment.
| Template | Use case | What it sets up |
|---|---|---|
minimal.conf | Evaluation, getting started | Database, LDAP, one transcribe, REST channel |
recommended.conf | Staging, internal deployments | All channels (LDAP, REST, GraphQL, MCP), Prometheus, health probes, indices |
production.conf | Production, real traffic | Everything in recommended + TLS, auth, network isolation, locked-down APIs |
minimal.conf gets IdentityScribe running with the fewest settings. It connects to one LDAP source, syncs one entry type, and exposes a REST API. Use it to evaluate Scribe or build up a config from scratch.
recommended.conf turns on every channel and adds monitoring. It includes user and group transcribes with indices, Prometheus metrics, health probes, and observability endpoints. Auth is disabled for evaluation, including an Observe opt-out that should stay limited to trusted local environments.
production.conf applies the full Production Checklist. It enables TLS on all endpoints, requires bearer token auth, isolates monitoring on a separate socket, and disables API schema endpoints. All secrets come from environment variables — no hardcoded defaults.
edirectory-idm.conf is an importable profile for eDirectory Identity Manager role, resource, and group membership
queries. Include it after your base config when you have user, role, and group transcribes. See
eDirectory Identity Manager Roles.
Required settings
Section titled “Required settings”Every template needs a database and an LDAP source.
ldap { url = "ldap://your-ldap-server:389" bind-dn = "cn=admin,dc=example,dc=com" bind-password = ${LDAP_BIND_PASSWORD}}
database { url = "postgresql://localhost:5432/identity_scribe" user = "scribe" password = ${DB_PASSWORD}}Secrets use ${ENV_VAR} substitution so they stay out of config files. See Secrets management for more.
Environment variables
Section titled “Environment variables”Environment variables follow the config path with dots converted to underscores:
Config path: monitoring.hints.persistence.enabledEnv var: SCRIBE_HINTS_PERSISTENCE_ENABLED| Type | Examples |
|---|---|
| Booleans | true, false, yes, no, on, off |
| Durations | 500ms, 5s, 30m, 1h, 2d |
| Sizes | 1k, 2m, 3g (bytes) |
| Numbers | Plain integers (no quotes) |
| Strings | Quoted "value" or unquoted simple-value |
The configuration reference lists every environment variable alongside its config path and default value.
Extending defaults with HOCON
Section titled “Extending defaults with HOCON”Customize defaults without copying them. These patterns keep configs short and pick up new defaults automatically on upgrade.
Append to arrays
Section titled “Append to arrays”Use += to add items after defaults:
monitoring.log.rules += {
action = include,
where = "scribe.operation~=Audit.*" }# Multiple items (use ${path} [...] pattern, not += [...])monitoring.log.rules = ${monitoring.log.rules} [ { action = include, where = "scribe.operation~=Debug.*" } { action = exclude, where = "scribe.operation~=Noisy.* duration.seconds<=10ms" }]
# Any array workshttp.cors.allow-origins += "http://localhost:3000"ssl.cipher-suites += "TLS_AES_256_GCM_SHA384"Prepend to arrays
Section titled “Prepend to arrays”Place items before defaults. For log rules, earlier items take priority:
# Your rule first, then defaults
monitoring.log.rules = [
{ action = include, where = "scribe.operation~=Critical.*" }
] ${monitoring.log.rules}Merge objects
Section titled “Merge objects”Objects merge automatically. Specify only what changes:
# Change port, inherit everything elsehttp.sockets.admin { port = 9001 }
# Override format, keep other log settingsmonitoring.log.format = "json"Inheritance chains
Section titled “Inheritance chains”These settings inherit from a parent section:
| Setting | Inherits from |
|---|---|
| Socket SSL | http.sockets.<name>.ssl ← http.ssl ← ssl |
| Socket CORS | http.sockets.<name>.cors ← http.cors |
| Auth caches | auth.bearer.cache, auth.ropc.cache, auth.ldap.cache ← auth.cache; local credentials are not cached |
| LDAP auth | auth.ldap ← ldap |
| Transcribe LDAP | transcribes.<name>.ldap ← ldap |
| Channel UI | channels.*.ui ← openapi.ui |
| Observe UI | monitoring.observe.ui ← openapi.ui |
| Retry services | retry.services ← retry |
Override at any level:
http.sockets.secure.ssl = ${http.ssl} {
# only these keys change
cert = "/custom/server.crt"
key = "/custom/server.key"
}Example: dev config
Section titled “Example: dev config”include required("production.conf")
# Priority rules + relaxed thresholdsmonitoring.log.rules = [ { action = include, where = "scribe.operation~=*.Dev*" } # Always log dev ops] ${monitoring.log.rules} [ { action = exclude, where = "duration.seconds<=2s" } # Relax timing]
# Extra CORS originshttp.cors.allow-origins += "http://localhost:3000"http.cors.allow-origins += "http://localhost:4321"Troubleshooting
Section titled “Troubleshooting”Configuration not taking effect
Section titled “Configuration not taking effect”- Check priority: A higher-priority source may be overriding your value
- Verify naming: Ensure underscores match dots in the config path
- Case sensitivity: Use the exact environment-variable spelling shown in the reference
Debug configuration loading
Section titled “Debug configuration loading”# Print resolved config (sensitive values masked)identity-scribe --printconfig
# Enable debug logging for config parsingSCRIBE_LOG_CONFIG=debug identity-scribeCommon issues
Section titled “Common issues”| Symptom | Cause | Solution |
|---|---|---|
| Env var ignored | Wrong prefix | Use SCRIBE_ not IDENTITY_SCRIBE_ |
| Value not parsed | Wrong format | Use HOCON format: 5s, true, 1024 |
| Config file not found | Wrong search path | Use --config or SCRIBE_CONFIG_FILE |
Related
Section titled “Related”- Configuration reference — Every setting, env var, and default value
- Deployment — Docker Compose and Kubernetes examples
- Upgrading — Migration from older config formats