Configuration

Configure IdentityScribe through HOCON files, environment variables, or CLI flags. This guide covers all configuration mechanisms with practical deployment examples.

Quick Reference: See reference.conf for inline documentation of all settings with their environment variable overrides.

Identity Scribe uses HOCON (Human-Optimized Config Object Notation) for configuration. Values are resolved in this order (highest priority first):

ldap {
  url = "ldap://your-ldap-server:389"
  bind-dn = "cn=admin,dc=example,dc=com"
  bind-password = "secret"
}

database {
  url = "postgresql://localhost:5432/identity_scribe"
  user = "scribe"
  password = "secret"
}

services:
  identity-scribe:
    image: identity-scribe:latest
    environment:
      SCRIBE_LDAP_URL: "ldap://ldap:389"
      SCRIBE_LDAP_BIND_DN: "cn=admin,dc=example,dc=com"
      SCRIBE_LDAP_BIND_PASSWORD: "${LDAP_ADMIN_PASSWORD}"
      SCRIBE_DATABASE_URL: "postgresql://postgres:5432/identity_scribe"
      SCRIBE_DATABASE_USER: "scribe"
      SCRIBE_DATABASE_PASSWORD: "${DB_PASSWORD}"
      SCRIBE_HTTP_PORT: "8080"
      SCRIBE_LOG_LEVEL: "info"

apiVersion: v1
kind: ConfigMap
metadata:
  name: identity-scribe-config
data:
  SCRIBE_LDAP_URL: "ldap://ldap-service:389"
  SCRIBE_DATABASE_URL: "postgresql://postgres-service:5432/identity_scribe"
  SCRIBE_HTTP_PORT: "8080"
  SCRIBE_LOG_LEVEL: "info"
  SCRIBE_CONCURRENCY: "16"
---
apiVersion: v1
kind: Secret
metadata:
  name: identity-scribe-secrets
type: Opaque
stringData:
  SCRIBE_LDAP_BIND_DN: "cn=admin,dc=example,dc=com"
  SCRIBE_LDAP_BIND_PASSWORD: "secret"
  SCRIBE_DATABASE_USER: "scribe"
  SCRIBE_DATABASE_PASSWORD: "secret"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: identity-scribe
spec:
  template:
    spec:
      containers:
      - name: identity-scribe
        envFrom:
        - configMapRef:
            name: identity-scribe-config
        - secretRef:
            name: identity-scribe-secrets

Environment variables generally follow the config path with dots converted to underscores. Some frequently-tuned settings use shorter aliases (notably SCRIBE_HINTS_* and SCRIBE_PROMETHEUS_*):

Config path: monitoring.hints.persistence.enabled
Env var:    SCRIBE_HINTS_PERSISTENCE_ENABLED

The application mode controls AUTO feature toggles:

• Dev modes (case-insensitive): dev, development, local, test
• Prod modes: Everything else (e.g., production, staging, uat)

Lookup order (highest to lowest):

1. CLI: -m <mode> or --mode <mode>
2. System property: -Dmode=<mode> or -Dapp.mode=<mode>
3. SCRIBE_APP_MODE environment variable
4. APP_MODE environment variable (Node.js-style fallback)
5. APP_ENV environment variable (Node.js-style fallback)
6. app.mode config value
7. Fallback: production

Component-specific log levels (inherit from log.level by default):

Set SCRIBE_LOG_MONITORING=off to disable wide-log output entirely, or SCRIBE_LOG_MONITORING=warn to only emit warnings and errors.

Third-party library log levels (default: warn):

Log format options (SLF4J SimpleLogger):

Log formatting is controlled by SLF4J SimpleLogger, which reads format options only once at JVM startup. These settings must be configured via JVM system properties—they cannot be changed at runtime via environment variables or config files.

Example: Enable timestamps with local time format:

java -Dorg.slf4j.simpleLogger.showDateTime=true \
     -Dorg.slf4j.simpleLogger.dateTimeFormat=HH:mm:ss.SSS \
     -jar identity-scribe.jar

Or via JAVA_TOOL_OPTIONS environment variable:

export JAVA_TOOL_OPTIONS="-Dorg.slf4j.simpleLogger.showDateTime=true -Dorg.slf4j.simpleLogger.dateTimeFormat=HH:mm:ss.SSS"
java -jar identity-scribe.jar

Leak Detection (HikariCP-style):

When enabled, segments open longer than the threshold trigger a warning with the creation stack trace. This helps identify resource leaks during development.

• off: Never run leak detection
• on: Always run leak detection
• auto: Enabled when app.mode is dev/development/local/test; disabled otherwise

Session-level PostgreSQL parameters applied to channel queries. Channels can override these in their own connection-hints section.

Note: work-mem values are validated against a strict allowlist (^[0-9]+\s*(B|kB|MB|GB|TB)$).

See HTTP Server Configuration for socket binding, TLS, and named sockets.

These standard environment variables control terminal behavior. They are not SCRIBE_-prefixed as they follow cross-platform conventions.

Color support is auto-detected based on TTY presence and CI environment (GitHub Actions, GitLab CI, CircleCI, Travis, Buildkite, Jenkins). See HTTP Server for details.

If you’re upgrading from a version that used IDENTITY_SCRIBE_* environment variables, rename them to SCRIBE_*:

# For shell scripts or .env files
sed -i 's/IDENTITY_SCRIBE_/SCRIBE_/g' .env

# For Kubernetes ConfigMaps/Secrets (backup first!)
kubectl get configmap identity-scribe-config -o yaml | \
  sed 's/IDENTITY_SCRIBE_/SCRIBE_/g' | \
  kubectl apply -f -

After migration, verify the resolved configuration:

identity-scribe --printconfig

This shows all resolved values with sources, helping identify any misconfigured variables.

1. Check priority: A higher-priority source may be overriding your value
2. Verify naming: Ensure underscores match dots in the config path
3. Case sensitivity: Environment variables are case-insensitive for lookup

# Print resolved config (sensitive values masked)
identity-scribe --printconfig

# Enable debug logging for Settings
SCRIBE_LOG_LEVEL=debug identity-scribe

HOCON supports a built-in mechanism for overriding any config key via environment variables:

# Enable with system property
identity-scribe -Dconfig.override_with_env_vars=true

# Override any key using CONFIG_FORCE_*
# Name mangling: _ → . (dot), __ → - (hyphen), ___ → _ (underscore)
CONFIG_FORCE_ldap_url=ldap://override        # → ldap.url
CONFIG_FORCE_ldap_use__keep__alive=true      # → ldap.use-keep-alive

This is orthogonal to SCRIBE_* variables and can override keys without explicit ${?...} substitution.