Remplacer les paramètres

Chaque paramètre de cette installation provient de l’une des quatre sources suivantes, qui se remplacent les unes après les autres : le fichier contenu dans l’image, deux fichiers situés dans le dossier de données et l’environnement dans lequel le processus s’exécute. Cette page décrit cet ordre, la notation d'un paramètre sous toutes ses formes, ainsi que les emplacements où une valeur confidentielle, telle qu'une clé API, doit ou ne doit pas figurer.

L'ordre des quatre lieux

• Le fichier « appsettings.json » intégré, dans le fichier image. Ce fichier se trouve dans le code source et répertorie chaque paramètre avec sa valeur par défaut ; il s'agit d'un guide de référence complet ;
• data/config/appsettings.json dans le dossier de données monté. Il s'agit du fichier propre à cette installation : il remplace le fichier intégré, et .gitignore le désactive, de sorte qu'aucune valeur qu'il contient ne se retrouve jamais dans le code source ;
• data/config/appsettings.<Omgeving>.json : le même dossier, avec le nom de l'environnement dans le nom du fichier, par exemple appsettings.Test.json. Prend le pas sur le fichier précédent, pour un deuxième environnement sur le même serveur qui ne nécessite qu'un seul paramètre différent ;
• l'environnement du processus : une variable d'environnement ou un argument de ligne de commande. L'emporte sur les trois fichiers.

Les deux fichiers du dossier de données sont mis à jour dès qu'une modification est effectuée : celle-ci est prise en compte en quelques secondes, sans redémarrage. Voir la section « Limitations » ci-dessous pour connaître les exceptions à cette règle.

Une institution, deux notations

Un paramètre est défini dans un fichier sous la forme d'une clé imbriquée suivie d'un deux-points, par exemple BesluitBron:Admin:Password. En tant que variable d'environnement, chaque deux-points est remplacé par un double trait de soulignement : BesluitBron__Admin__Password. Ces deux formes renvoient exactement au même paramètre ; le choix de la forme dépend de la provenance de la valeur, et non de la signification du paramètre.

Le fichier docker-compose.production.yml fourni effectue une étape intermédiaire pour certains paramètres couramment utilisés : le fichier compose lit un nom propre dans .env, tel que BBN_ADMIN_PASSWORD, et le convertit lui-même en BesluitBron__Admin__Password dans l'environnement du conteneur. Un fichier compose personnalisé n'a pas besoin de reproduire cette étape intermédiaire et peut définir directement la forme BesluitBron__.

Le fichier d'exemple

Si le fichier « data/config/appsettings.json » n'existe pas encore, le service crée, au démarrage, un fichier « data/config/appsettings.json.sample » documenté à côté, contenant des explications et la valeur par défaut de chaque paramètre. Cet exemple est actualisé à chaque démarrage tant que le fichier réel n'existe pas encore, afin qu'il corresponde toujours à la version en cours d'exécution ; depuis la version 1.3.69, l'en-tête indique la version qui l'a généré, ce qui permet à un administrateur de vérifier si l'exemple et l'installation en cours d'exécution sont toujours synchronisés. Le fichier réel n’est jamais modifié par le service.

Une valeur secrète

Le fichier intégré « appsettings.json » est géré par un système de contrôle de version ; par conséquent, toute valeur qui y est enregistrée est accessible à toute personne capable de lire le code source. Une valeur confidentielle, telle que la clé DeepL disponible à l'adresse BesluitBron:Translation:DeepLApiKey, ne doit donc figurer que dans le fichier « data/config/appsettings.json » du répertoire de données ou sous forme de variable d'environnement (BesluitBron__Translation__DeepLApiKey), et en aucun cas dans le fichier intégré.

Voir ce qui s'applique

L'écran « Paramètres » de la console d'administration affiche, pour chaque paramètre, la valeur actuellement en vigueur et sa source, et signale également les fichiers présents dans le dossier de données mais qui ne sont pas lus, par exemple en raison d'un nom incorrect. Voir Instellingen.

Restrictions

• Toute modification apportée à l'un des deux fichiers du répertoire de données est automatiquement prise en compte ; en revanche, une modification de l'environnement du processus, d'une variable d'environnement ou de la ligne de commande nécessite un redémarrage, car celle-ci n'est lue qu'une seule fois, au démarrage ;
• Un paramètre défini au démarrage, tel que la liste des sources proposées, ne s'adapte pas automatiquement lorsqu'un fichier est rechargé en temps réel. Voir Installatie et Uitrol en Beheer.