Every setting in this installation comes from one of four sources, which take precedence in the following order: the file contained within the image, two files in the data folder, and the environment in which the process is running. This page describes that order, the notation for a setting in each form, and where a secret value, such as an API key, should and should not be placed.
The order of the four places
- The built-in
appsettings.json, in the image. That file is included in the source code and documents every setting along with its default value; it is the complete reference; data/config/appsettings.jsonin the mounted data folder. This is the file for this installation: it overwrites the built-in file, and.gitignoreexcludes it, so any value entered there will never end up in the source code;data/config/appsettings.<Omgeving>.json– the same folder, with the environment name included, for exampleappsettings.Test.json. Takes precedence over the previous file, for a second environment on the same server that requires only one different setting;- the process environment: an environment variable or a command-line argument. Takes precedence over all three files.
Any changes to the files in the data folder are detected within a few seconds, without the need to restart. See ‘Limitations’ below for an exception to this.
One institution, two notations
A setting is stored in a file as a nested key with a colon, for example BesluitBron:Admin:Password. When used as an environment variable, each colon is replaced by a double underscore: BesluitBron__Admin__Password. Both forms refer to exactly the same setting; which form is used depends on where the value comes from, not on what the setting means.
The included docker-compose.production.yml file performs an intermediate step for a few commonly used configurations: the compose file reads a custom name from .env, such as BBN_ADMIN_PASSWORD, and converts it itself to BesluitBron__Admin__Password within the container’s environment. A custom compose file does not need to replicate this intermediate step and may specify the BesluitBron__ format directly.
The sample file
If data/config/appsettings.json does not yet exist, the service will, upon start-up, create a documented data/config/appsettings.json.sample alongside it, containing an explanation and the default value for each setting. This example is updated at every start-up whilst the actual file does not yet exist, ensuring it always matches the running version; since version 1.3.69, the header line specifies which version wrote it, so that an administrator can check whether the example and the running installation are still in sync. The actual file is never modified by the service.
A secret value
The built-in appsettings.json file is under version control, so any value stored there will be visible to anyone who can read the source code. A secret value, such as the DeepL key at BesluitBron:Translation:DeepLApiKey, should therefore only be placed in data/config/appsettings.json within the data folder or as an environment variable (BesluitBron__Translation__DeepLApiKey), and never in the built-in file.
Find out what applies
The “Settings” screen in the management console shows, for each setting, the value that currently applies and where it comes from, and also lists any files in the data folder that are not being read – for example, because they have the wrong name. See Instellingen.
Restrictions
- Any change to either of the files in the data folder is automatically detected; a change to the process environment, an environment variable or the command line requires a restart, as these are only read once, at start-up;
- A setting that is defined at start-up – such as which sources are offered – does not automatically update when a file is reloaded live. See Installatie and Uitrol en Beheer.