3.3. Overriding configuration

The config/toa-server.yml file shipped with the release is the primary source of configuration, but every key documented in this chapter can also be overridden from the environment or the command line without editing the YAML. The mechanism is provided by Spring Boot and is useful when the server runs in containers, when the same installation serves several environments, or simply to flip a single switch for a one-off restart.

3.3.1. External configuration file

The java -jar command line used by the systemd unit (Installing TOA server) points Spring Boot at the config/ folder next to the jar:

--spring.config.additional-location=file:/opt/toa-server/config/

Spring Boot loads every application.* and application-*.* file it finds there, in addition to the toa-server.yml already imported by the jar. You can drop a second file next to toa-server.yml - for example application-site.yml - to keep site-specific overrides separate from the shipped configuration. This is handy when the shipped toa-server.yml is managed by configuration-management tooling and a human-authored override has to ride on top.

3.3.2. Environment variables

Any configuration key can be set via an environment variable using Spring Boot’s relaxed binding convention:

  • uppercase the key,

  • replace dots . and hyphens - with underscores _,

  • for list entries, use a numeric index.

Examples:

YAML key

Equivalent environment variable

toa-server.dataRoot

TOA_SERVER_DATAROOT

server.port

SERVER_PORT

toa-server.domains[0].code

TOA_SERVER_DOMAINS_0_CODE

toa-server.domains[0].templates.refresh

TOA_SERVER_DOMAINS_0_TEMPLATES_REFRESH

logging.level.com.lightcomp.tahiti

LOGGING_LEVEL_COM_LIGHTCOMP_TAHITI

In a systemd unit this translates into one or more Environment=KEY=value lines, or an EnvironmentFile= pointing at a drop-in file. See man systemd.exec for the full syntax.

3.3.3. Command-line arguments

Any key can also be passed directly after the jar on the command line:

# java -jar /opt/toa-server/toa-server.jar \
    --spring.config.additional-location=file:/opt/toa-server/config/ \
    --server.port=9090 \
    --logging.level.com.lightcomp.tahiti.office.addon=DEBUG

Command-line arguments are the highest-priority source and are useful for short-lived diagnostic restarts. They are less convenient for permanent configuration because they have to be reproduced in every systemd unit and are easy to forget after a host reinstall.

3.3.4. Precedence

When the same key is specified in more than one place, the value that wins follows Spring Boot’s standard order (highest priority first):

  1. Command-line arguments (--key=value).

  2. Operating system environment variables.

  3. External toa-server.yml loaded via spring.config.additional-location.

  4. Defaults baked into the server jar.

In practice: keep the permanent configuration in toa-server.yml, use environment variables for per-host overrides (dev vs test vs prod), and reach for the command line only for temporary diagnostic runs.