Installation, BesluitBron documentatie

BesluitBron fonctionne en tant que service public sur besluitbron.nl et ne nécessite aucune installation pour une utilisation courante. Une installation sur site est nécessaire lorsque le trafic doit rester au sein du réseau interne. Elle est également nécessaire lorsque l'organisation souhaite déterminer elle-même quelles sources sont proposées. La page publique « Exécuter soi-même » présente les éléments à prendre en compte ; cette page décrit la procédure à suivre.

Le logiciel est disponible sous licence EUPL-1.2.

Télécharger le logiciel

Le code source est fourni sur demande via l'adresse e-mail indiquée sur la page de contact. Une réponse à toute demande est envoyée dans un délai de deux jours ouvrables. Il n'existe pas encore de dépôt public ; la raison en est mentionnée dans les mentions légales.

L'image du conteneur provient d'un registre externe à ce site. L'adresse figure sur la page publique « Exécuter soi-même », avec la commande permettant de la récupérer et la version utilisée par cette installation comme balise. Cette page n'affiche l'adresse que si l'administrateur l'a saisie sous BesluitBron:Distribution:ImageReference ; l'image est disponible pour amd64 et arm64.

Si une installation ne spécifie pas d'adresse, l'image est créée à partir du code source. Le fichier Dockerfile correspondant se trouve dans le code source et est le même que celui utilisé pour créer l'installation publique. À partir de la version 1.3.21.

Conditions générales

Un environnement capable d'exécuter des conteneurs, sur amd64 ou arm64 ;
Connexions HTTPS sortantes vers les plateformes sources proposées, voir Bronnen ;
Un volume de disque pour le dossier de données : journal des requêtes, exportations et, le cas échéant, le certificat ;
PostgreSQL 18 et option, lorsque les paramètres et le journal doivent être stockés dans une base de données plutôt que dans des fichiers. À partir de la version 1.3.51 ; jusqu'à la version 1.3.50 incluse, il s'agissait de PostgreSQL 17. Une base de données existante de version 17 n'est pas automatiquement prise en charge ; voir Uitrol en Beheer.

Avec le fichier docker-compose.production.yml

Le référentiel fournit docker-compose.production.yml. Cette configuration part du principe que Caddy s'exécute lui-même dans un conteneur et se charge du protocole TLS ; le service ne publie alors pas de port propre sur l'hôte. Voir Uitrol en Beheer pour une illustration de cette configuration.

Créez une seule fois le réseau partagé sur lequel Caddy et le service peuvent communiquer : docker network create proxy.
Créez un fichier « .env » à côté du fichier « compose », contenant au moins trois mots de passe : BBN_INSTALL_PASSWORD (le rôle qui crée et met à jour le modèle de données), BBN_WEB_PASSWORD (le rôle sous lequel le service s'exécute) et BBN_ADMIN_PASSWORD (la console d'administration ; sans celui-ci, le service refuse de démarrer). BBN_INSTALL_USER, BBN_WEB_USER, BBN_ADMIN_USER, BBN_DATABASE et BBN_PROJECT sont facultatifs et ont une valeur par défaut. La relation entre un tel nom de .env et un paramètre du service lui-même est décrite à l’adresse Instellingen Overschrijven.
Démarrez le service et la base de données :

docker compose -f docker-compose.production.yml up -d

Si un deuxième environnement fonctionne en parallèle de celui-ci sur le même serveur, par exemple un environnement de test, celui-ci se voit attribuer son propre .env avec ses propres adresses BBN_PROJECT et BBN_ENVIRONMENT=Test. Les deux fonctionnent à partir du même fichier « compose » ; voir les explications en haut de ce fichier pour la nomenclature.
Mise à jour vers une nouvelle version :

docker compose -f docker-compose.production.yml pull
docker compose -f docker-compose.production.yml up -d

Consultez la page Uitrol en Beheer pour savoir ce qu’il advient du modèle de données dans ce contexte, ainsi que les étapes à suivre pour une version majeure de PostgreSQL.

Les étapes

Récupérez l'image du conteneur ou compilez-la à partir du code source si aucune adresse n'est connue. Les commandes permettant de démarrer le service et la base de données se trouvent ci-dessus, sous « Avec docker-compose.production.yml ».
Définissez le mot de passe administrateur. À partir de la version 1.3.21, l'image ne fournit plus de mot de passe par défaut et le service refuse de démarrer si aucun mot de passe n'a été défini. Il est fourni à l'adresse BesluitBron:Admin:Password, dans la configuration recommandée disponible sur BBN_ADMIN_PASSWORD, dans la section « .env ». Jusqu'à la version 1.3.21, le service démarrait avec un mot de passe par défaut public, ce qui déclenchait un avertissement dans la console.
Configurez l'adresse publique. Les adresses MCP affichées et les liens d'exportation pointeront alors vers votre propre installation plutôt que vers BesluitBron.nl.
Choisissez les sources à activer. Chaque source dispose de son propre interrupteur ; au moins l'une d'entre elles doit rester allumée, voir Connectorregister.
Mettez TLS et amont. Dans la configuration recommandée, un proxy inversé se charge de la terminaison TLS et le conteneur communique simplement en HTTP au sein de son propre réseau ; voir Uitrol en Beheer.
Indiquez qui réalise l'installation, sous « BesluitBron:Organisation » : nom, adresse, adresse e-mail et numéro d'enregistrement. Tant que les champs « nom » et « adresse e-mail » sont vides, le site n'affiche ni mentions légales ni informations sur l'organisation, car des mentions légales partiellement remplies pourraient être interprétées comme une réponse. À partir de la version 1.3.7.
Indiquez BesluitBron:Organisation:Logo suivi du logo de l'organisation, si celle-ci en possède un. Il peut s'agir d'une adresse complète vers son propre site web ou d'un chemin d'accès à un fichier sur wwwroot. Le logo n'apparaît pas à l'écran : il est intégré aux données lisibles par les robots de chaque page publique, ce qui permet à un moteur de recherche d'identifier l'éditeur du site. Vous pouvez laisser ce champ vide ; dans ce cas, aucun logo ne sera publié. À partir de la version 1.3.21.
Saisissez BesluitBron:Donation lorsque le site vous demande une contribution, et laissez ce champ vide s'il ne le fait pas. Tant que le champ Iban est vide, aucun bouton de don n'apparaît dans la barre, aucune fenêtre ne s'ouvre et l'adresse /nl/doneren n'existe pas. Remplissez également BeneficiaryName avec le nom figurant sur le compte et Reference avec la mention que le donateur souhaite indiquer. SmallPrint correspond à votre propre phrase de conclusion sous la fenêtre, par exemple concernant la déductibilité fiscale et la destination des fonds ; ce texte s'affiche tel quel et n'est pas traduit. À partir de la version 1.3.29.
Recréez les codes QR après avoir modifié le compte, à l'aide de tools/make-epc-qr.py, et configurez BesluitBron:Donation:QrIban sur ce même compte. La fenêtre n'affiche les codes que tant que ces deux éléments correspondent. Personne ne vérifie les codes QR, et un code issu d'une installation précédente est impossible à distinguer d'un code valide, alors qu'il redirige l'argent vers une autre destination. À partir de la version 1.3.29.
Entrez BesluitBron:Donation:PaymentFormUrl dans le champ « Adresse » de la page de paiement du service de dons, le cas échéant, puis ajoutez cette même adresse à BesluitBron:Security:FrameSources. Sans cette deuxième étape, le navigateur bloquera la fenêtre. Si ce champ reste vide, la fenêtre ne propose que le virement bancaire, ce qui constitue une configuration pleinement fonctionnelle. À partir de la version 1.3.29.
Indiquez BesluitBron:Support:ForumUrl comme destination pour les questions et les problèmes, ou laissez le champ vide. Si la valeur par défaut est conservée, l'installation redirigera ses utilisateurs vers le forum de l'auteur, voir Contact en Meldingen. À partir de la version 1.3.7.
Ne remplissez le champ « BesluitBron:Distribution:ImageReference » que si cette installation fournit elle-même une image ou en héberge une, en indiquant l'adresse sans balise. La page « Exécuter soi-même » affiche alors la commande permettant de la récupérer, avec la version en cours d'exécution comme balise. Si ce champ reste vide, cette page ne mentionne que le code source. RegistryOperator indique qui gère ce registre et s'affiche avec la commande. À partir de la version 1.3.21.
Laissez « BesluitBron:Mcp » tel quel, sauf si un client reçoit un refus que personne ne peut expliquer. Le service conserve pendant trente minutes l'information relative au connecteur sur lequel une session MCP a été ouverte, à compter de la dernière requête de cette session, et s'en sert pour refuser un client qui s'adresse ensuite à un autre connecteur. SessionBindingRetentionMinutes modifie cette durée de trente minutes. À partir de la version 1.3.7.
Saisissez BesluitBron:Mail si le site doit pouvoir envoyer des messages : la passerelle, le port, le nom d'utilisateur, le mot de passe et une adresse d'expéditeur vérifiée par cette passerelle. Si l'option « Enabled » est désactivée, le bouton « J'aime » sur les pages publiques ne demande pas l'envoi d'un message, car un message qui n'arrive nulle part ne doit pas être demandé. À partir de la version 1.3.34.
Une base de données est requise et le service ne démarre pas sans elle. Jusqu'à la version 1.3.72 incluse, cela ne s'appliquait qu'à une partie des fonctionnalités, comme l'envoi de messages : la file d'attente correspondante est une table ; ainsi, sans base de données, aucun message n'était envoyé, le bouton « J'aime » ne demandait pas de message et le bouton de test était désactivé. À partir de la version 1.3.73, le service refuse de démarrer sans base de données et indique laquelle des trois éléments manque : le commutateur, la connexion pour le modèle de données ou la connexion pour le service lui-même.
Vérifiez ces paramètres à l'aide du bouton « Envoyer un message test » sur l'écran Paramètres de la console d'administration. Le message est envoyé à l'adresse indiquée dans BesluitBron:Organisation:Email et à aucune autre adresse. Il est d'abord placé dans la file d'attente ; actualisez la page pour voir ce que la passerelle en a dit. Si cela ne fonctionne pas, le message indiquera ce que la passerelle a elle-même signalé, par exemple que la connexion a été refusée ou que la connexion a échoué. Le statut « Envoyé » indique que la passerelle a accepté le message, sans préciser s’il a été remis. À partir de la version 1.3.34.
Laissez BesluitBron:Corpus tel quel, sauf si l'installation ne doit pas effectuer d'appels sortants. Ces paramètres déterminent comment la taille de chaque source est mesurée pour le graphique de la page d'accueil : IntervalHours correspond à un jour, Enabled désactive la mesure, MaximumShrinkPercent est le seuil en dessous duquel une sortie est refusée (un cinquième) et TimeoutSeconds correspond au coût maximal autorisé pour une plateforme. IntervalHours ne peut qu’augmenter : une valeur inférieure à 24 est portée à 24. StatePath est le fichier dans lequel le serveur enregistre la date de sa dernière mesure ; par défaut, il s’agit de ./data/corpus-size.json ; sans ce fichier, il effectue une nouvelle mesure à chaque démarrage, il faut donc le laisser dans le répertoire monté. Le fichier peut être supprimé : cela entraîne une mesure supplémentaire. Lorsque la mesure est désactivée, la page affiche des chiffres mesurés manuellement, accompagnés de la date de cette mesure ; vous pouvez donc la désactiver sans que rien ne soit perdu. Voir Startpagina. À partir de la version 1.3.41.
Consultez le site /health, qui présente chaque connecteur proposé séparément.

Authentification à deux facteurs

Chaque compte de la console d'administration nécessite une authentification à deux facteurs, y compris le premier compte. Une fois le mot de passe administrateur défini, la console vous demande, lors de la première connexion, d'associer une application d'authentification, à l'aide d'un code QR et d'une clé manuelle. Elle affiche ensuite dix codes de secours à usage unique ; conservez-les en lieu sûr. À partir de la version 1.3.85.

En cas de mot de passe oublié, c'est le titulaire du compte qui le réinitialise lui-même, à l'aide d'un lien envoyé à l'adresse e-mail associée au compte. Veillez donc à saisir une adresse e-mail pour chaque compte. En cas de perte de l'application d'authentification ou des codes de secours, il faut faire appel à un administrateur : celui-ci réinitialise l'authentification à deux facteurs depuis l'écran « Utilisateurs », après quoi le titulaire du compte reçoit un nouveau code pour rétablir la connexion. Configurez « BesluitBron:Support:MfaResetPhoneNumber » sur le numéro de téléphone auquel le titulaire du compte peut s'adresser à cet effet ; cette configuration affiche le numéro sur l'écran de connexion.

Pour le premier compte, accessible depuis l'extérieur du conteneur, il existe une procédure de récupération au cas où le mot de passe ou l'authentification à deux facteurs ne fonctionnerait plus. Le paramètre « BesluitBron:BreakGlass:AllowedInitialLoginAddresses » indique l'adresse ou la plage d'adresses à partir de laquelle la prochaine connexion après une telle récupération est autorisée ; ce champ est obligatoire dès lors que l’option « BesluitBron:BreakGlass:Enabled » est activée, sinon le service refuse de démarrer. Une fois cette option configurée, la restauration s’effectue en plaçant un fichier vide nommé « reset-password.trigger » ou « reset-mfa.trigger » dans le dossier « break-glass » situé dans le dossier de données. Le service ne procède à cette restauration que si la messagerie est configurée et qu'au moins un administrateur actif dispose d'une adresse e-mail ; il les avertit tous lorsque cela se produit ; sans messagerie opérationnelle, rien ne se passe. À partir de la version 1.3.86 ; jusqu’à la version 1.3.85 incluse, ce champ d’adresse était facultatif et une valeur vide autorisait l’accès à tout le monde.

Le cookie de connexion de la console est valable une heure, cette durée étant prolongée à chaque action effectuée au cours de cette heure ; seule une inactivité réelle met fin à la session. À partir de la version 1.3.86 ; jusqu'à la version 1.3.85 incluse, cette durée était de vingt-quatre heures.

Pour un script qui récupère automatiquement des données, comme un robot d'indexation de documentation, il existe une procédure de connexion distincte. Cette procédure ne fonctionne que sur un environnement autre que « Production », et uniquement pour un appel provenant du même appareil (localhost) ; un appel provenant d'ailleurs sera refusé, même avec la clé appropriée. Définissez BesluitBron:Automation:ApiKey sur une clé pour activer cette méthode ; si ce champ reste vide, la méthode reste désactivée, quel que soit l'environnement. Le script transmet cette clé dans l’en-tête X-Automation-Api-Key. Il crée ainsi son propre compte, associe sa propre authentification à deux facteurs et se connecte autant de fois que nécessaire. Une fois son travail terminé, le script supprime lui-même le compte. Ces cinq adresses figurent également, sur un environnement autre que « Production », dans la liste disponible sur /api, voir Swagger. À partir de la version 1.3.86.

Après l'installation

Connectez un assistant en suivant les instructions disponibles à l'adresse Claude Aansluiten, en remplaçant « BesluitBron.nl » par votre propre adresse. Définissez ensuite une durée de conservation pour le dossier de données ; voir Logging en Verantwoording.

Restrictions

Une modification de la configuration de source est appliquée au démarrage. Une modification nécessite donc un redémarrage ;
Les adresses MCP ne font l'objet d'aucune authentification. Si vous souhaitez modifier cela au sein de votre propre environnement, vous devez le configurer au niveau du réseau ou du proxy inverse ; voir Openbaarheid en Persoonsgegevens.