Skip to content

Configuration loading model

All main processes read application.conf as the top-level configuration entry.

HOCON basics used by {{ product_name }}

{{ product_name }} uses Typesafe Config and HOCON syntax:

  • Hierarchical objects and dotted keys (db.maximumPoolSize = 20)
  • Includes (include "db.conf")
  • Key-to-key substitution (dataSource.currentSchema = ${db.schema})
  • Optional environment substitution (Authorization = "Bearer ${?OTLP_TOKEN}")
  • Comments and human-readable formatting

Top-level application.conf examples

license.dataDir = "/var/lib/sae"
include "monitor.conf"
include "db.conf"
include "alpine.conf"
include "override"

include "db.conf"
monitor.enabled = false
include "override"

How include override works

In HOCON, include "override" resolves override.conf (or JSON/properties variants).

This project ships a default empty override.conf, and you can add environment values as needed.

Effective precedence

For keys defined multiple times, effective order is:

  1. CONFIG_FORCE_* environment overrides (when config.override_with_env_vars=true)
  2. JVM system properties (for example -Ddb.maximumPoolSize=30)
  3. override.conf (included last)
  4. Included defaults (alpine.conf, db.conf, monitor.conf)
  5. Earlier values in application.conf

If config.override_with_env_vars is disabled, step 1 is skipped.

Shared default configuration files

File Scope Purpose Typical keys
db.conf alpine-server, alpine-admin-cli Database and pool defaults db.maximumPoolSize, db.dataSource.serverName, db.dataSource.ssl
monitor.conf Server-side only (alpine-server) Metrics and tracing registry settings monitor.enabled, monitor.registries.prometheus.*, monitor.tracing.*
alpine.conf Server-side only (alpine-server) Endpoint and service runtime settings alpine.endpoints, alpine.settings.*, alpine.services.*

These defaults are packaged with deployment artifacts. For maintainable upgrades, keep them unchanged and place environment-specific values in override.conf.

Logging configuration file (logback.xml)

Logging transport is configured outside HOCON in logback.xml.

  • logback.xml is loaded by Logback at process startup.
  • It is not part of application.conf include order.
  • CONFIG_FORCE_* does not override logback.xml settings.
  • Restart affected processes after changes.

See Reference: logback.xml for setting-level details and syslog listener prerequisites.

Runtime location and persistence

Runtime config files are deployed under resources/.

For containers, map resources/ to an external persistent volume and place override.conf there.

Server vs CLI monitoring configuration

  • alpine-server includes monitor.conf.
  • CLI processes do not load monitor.conf by default.
  • CLI defaults set monitor.enabled = false in their application.conf.