Jede Einstellung dieser Installation stammt aus einer von vier Quellen, die sich nacheinander überschreiben: die Datei im Image, zwei Dateien im Datenordner und die Umgebung, in der der Prozess läuft. Diese Seite beschreibt diese Reihenfolge, die Notation einer Einstellung in jeder Form und wo ein geheimer Wert, wie beispielsweise ein API-Schlüssel, hingehört und wo nicht.
Die Reihenfolge von vier Orten
- Die integrierte Datei „
appsettings.json“ im Image. Diese Datei ist im Quellcode enthalten und dokumentiert jede Einstellung mit ihrem Standardwert; sie dient als umfassendes Nachschlagewerk; data/config/appsettings.jsonim eingebundenen Datenordner. Dies ist die Datei dieser Installation: Sie überschreibt die integrierte Datei, und.gitignoreschließt sie aus, sodass ein darin enthaltener Wert niemals in den Quellcode gelangt;data/config/appsettings.<Omgeving>.jsonim selben Ordner, wobei der Name die Umgebung enthält, zum Beispielappsettings.Test.json. Diese Datei hat Vorrang vor der vorherigen, wenn es sich um eine zweite Umgebung auf demselben Server handelt, die sich nur in einer Einstellung unterscheidet;- die Prozessumgebung: eine Umgebungsvariable oder ein Argument auf der Befehlszeile. Gewinnt gegenüber allen drei Dateien.
Beide Dateien im Datenordner werden bei einer Änderung aktualisiert: Die Änderung wird innerhalb weniger Sekunden übernommen, ohne dass ein Neustart erforderlich ist. Eine Ausnahme hierzu finden Sie unter „Einschränkungen“ weiter unten.
Eine Einrichtung, zwei Schreibweisen
Eine Einstellung wird in einer Datei als verschachtelter Schlüssel mit einem Doppelpunkt angegeben, zum Beispiel BesluitBron:Admin:Password. Als Umgebungsvariable wird jeder Doppelpunkt durch einen doppelten Unterstrich ersetzt: BesluitBron__Admin__Password. Beide Formen beziehen sich auf genau dieselbe Einstellung; welche Form verwendet wird, hängt davon ab, woher der Wert stammt, und nicht davon, was die Einstellung bedeutet.
Die mitgelieferte Datei „docker-compose.production.yml“ führt für einige häufig verwendete Einstellungen einen Zwischenschritt durch: Die Compose-Datei liest einen eigenen Namen aus „.env“ aus, beispielsweise „BBN_ADMIN_PASSWORD“, und wandelt diesen in der Containerumgebung selbst in „BesluitBron__Admin__Password“ um. Eine eigene Compose-Datei muss diesen Zwischenschritt nicht übernehmen und kann die Form „BesluitBron__“ direkt verwenden.
Die Beispieldatei
Falls die Datei „data/config/appsettings.json“ noch nicht existiert, erstellt der Dienst beim Start eine dokumentierte Datei „data/config/appsettings.json.sample“ daneben, die Erläuterungen sowie den Standardwert für jede Einstellung enthält. Dieses Beispiel wird bei jedem Start aktualisiert, solange die eigentliche Datei noch nicht vorhanden ist, sodass es immer zur laufenden Version passt; in der Kopfzeile wird seit Version 1.3.69 angegeben, welche Version es erstellt hat, sodass ein Administrator erkennen kann, ob das Beispiel und die laufende Installation noch übereinstimmen. Die eigentliche Datei wird vom Dienst niemals verändert.
Ein geheimer Wert
Die integrierte Datei „appsettings.json“ unterliegt der Versionsverwaltung, sodass ein dort hinterlegter Wert für jeden lesbar ist, der den Quellcode einsehen kann. Ein geheimer Wert, wie beispielsweise der DeepL-Schlüssel unter BesluitBron:Translation:DeepLApiKey, gehört daher ausschließlich in die Datei „data/config/appsettings.json“ im Datenordner oder als Umgebungsvariable (BesluitBron__Translation__DeepLApiKey), niemals in die integrierte Datei.
Sehen, was gilt
Der Bildschirm „Einstellungen“ der Verwaltungskonsole zeigt für jede Einstellung den aktuell gültigen Wert und die Quelle an, aus der dieser stammt, und weist zudem auf eine Datei hin, die sich zwar im Datenordner befindet, aber nicht gelesen wird – beispielsweise aufgrund eines falschen Namens. Siehe Instellingen.
Einschränkungen
- Eine Änderung in einer der beiden Dateien im Datenordner wird automatisch übernommen; eine Änderung in der Prozessumgebung, einer Umgebungsvariablen oder der Befehlszeile erfordert einen Neustart, da diese nur einmal beim Start gelesen wird;
- Eine beim Start festgelegte Einstellung – beispielsweise, welche Quellen angeboten werden – ändert sich nicht automatisch, wenn eine Datei live neu geladen wird. Siehe Installatie und Uitrol en Beheer.