.. _configure-overrides:

=========================
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.

External configuration file
===========================

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

.. code-block:: text

   --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.

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.

Command-line arguments
======================

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

.. code-block:: console

   # 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.

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):

#. Command-line arguments (``--key=value``).
#. Operating system environment variables.
#. External ``toa-server.yml`` loaded via
   ``spring.config.additional-location``.
#. 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.