Elke instelling van deze installatie komt uit een van vier plekken, die na elkaar overschrijven: het bestand dat in het image zit, twee bestanden op de gegevensmap en de omgeving waarin het proces draait. Deze pagina beschrijft die volgorde, de notatie van een instelling in elke vorm en waar een geheime waarde, zoals een API-sleutel, wel en niet hoort.
De volgorde van vier plekken
- Het ingebouwde
appsettings.json, in het image. Dat bestand staat in de broncode en documenteert elke instelling met haar standaardwaarde; het is de volledige naslag; data/config/appsettings.json, op de gemounte gegevensmap. Dit is het bestand van déze installatie: het overschrijft het ingebouwde bestand, en.gitignoresluit het uit, dus een waarde erin komt nooit in de broncode terecht;data/config/appsettings.<Omgeving>.json, dezelfde map, met de omgeving in de naam, bijvoorbeeldappsettings.Test.json. Wint van het vorige bestand, voor een tweede omgeving op dezelfde server die maar één instelling anders wil hebben;- de omgeving van het proces: een environment-variabele of een argument op de opdrachtregel. Wint van alle drie de bestanden.
Beide bestanden op de gegevensmap volgen een wijziging: zij wordt binnen enkele seconden opgepikt, zonder herstart. Zie "Beperkingen" hieronder voor wat daarop een uitzondering is.
Eén instelling, twee notaties
Een instelling staat in een bestand als geneste sleutel met een dubbele punt, bijvoorbeeld BesluitBron:Admin:Password. Als environment-variabele wordt elke dubbele punt een dubbele underscore: BesluitBron__Admin__Password. Beide vormen wijzen naar precies dezelfde instelling; welke vorm wordt gebruikt hangt af van waar de waarde vandaan komt, niet van wat de instelling betekent.
Het meegeleverde docker-compose.production.yml neemt voor een paar veelgebruikte instellingen een tussenstap: het composebestand leest een eigen naam uit .env, zoals BBN_ADMIN_PASSWORD, en zet die zelf om naar BesluitBron__Admin__Password in de omgeving van de container. Een eigen composebestand hoeft die tussenstap niet over te nemen en mag de BesluitBron__-vorm rechtstreeks zetten.
Het voorbeeldbestand
Bestaat data/config/appsettings.json nog niet, dan schrijft de dienst bij het starten een gedocumenteerd data/config/appsettings.json.sample ernaast, met uitleg en de standaardwaarde bij elke instelling. Dat voorbeeld wordt bij elke start ververst zolang het echte bestand er nog niet is, zodat het altijd bij de draaiende versie past; de kopregel noemt sinds versie 1.3.69 welke versie het heeft geschreven, zodat een beheerder kan zien of het voorbeeld en de draaiende installatie nog gelijk lopen. Het echte bestand wordt nooit door de dienst aangeraakt.
Een geheime waarde
Het ingebouwde appsettings.json staat onder versiebeheer, dus een waarde die daarin komt te staan is een waarde die voor iedereen leesbaar is die de broncode kan lezen. Een geheime waarde, zoals de DeepL-sleutel onder BesluitBron:Translation:DeepLApiKey, hoort daarom alleen in data/config/appsettings.json op de gegevensmap of als environment-variabele (BesluitBron__Translation__DeepLApiKey), nooit in het ingebouwde bestand.
Zien wat er geldt
Het scherm "Instellingen" van de beheerconsole toont per instelling de waarde die op dit moment geldt en de plek waar die vandaan komt, en noemt ook een bestand dat op de gegevensmap staat maar niet wordt gelezen, bijvoorbeeld door een verkeerde naam. Zie Instellingen.
Beperkingen
- Een wijziging in een van beide bestanden op de gegevensmap wordt automatisch opgepikt; een wijziging in de omgeving van het proces, een environment-variabele of de opdrachtregel, vraagt een herstart, want die wordt maar één keer gelezen, bij het starten;
- een instelling die bij het starten wordt vastgelegd, zoals welke bronnen worden aangeboden, verandert niet vanzelf mee met een bestand dat live wordt herladen. Zie Installatie en Uitrol en Beheer.