Installation

BesluitBron wird als öffentlicher Dienst unter besluitbron.nl betrieben und muss für den normalen Gebrauch nicht installiert werden. Eine eigene Installation ist erforderlich, wenn der Datenverkehr innerhalb des eigenen Netzwerks bleiben soll. Sie ist auch erforderlich, wenn die Organisation selbst bestimmen möchte, welche Quellen angeboten werden. Auf der öffentlichen Seite „Selbst betreiben“ werden die zu berücksichtigenden Aspekte aufgeführt; auf dieser Seite wird die Vorgehensweise beschrieben.

Die Software steht unter der EUPL 1.2 zur Verfügung.

Die Software herunterladen

Der Quellcode wird auf Anfrage über die E-Mail-Adresse auf der Kontaktseite zur Verfügung gestellt. Eine Anfrage wird innerhalb von zwei Werktagen beantwortet. Es gibt noch kein öffentliches Repository; der Grund dafür wird im Impressum genannt.

Das Container-Image stammt aus einer Registry außerhalb dieser Website. Die Adresse ist auf der öffentlichen Seite „Selbst ausführen“ zu finden, zusammen mit der Anweisung zum Abrufen und der Version, die diese Installation ausführt, als Tag. Diese Seite zeigt die Adresse nur an, wenn der Administrator sie unter BesluitBron:Distribution:ImageReference eingegeben hat; das Image ist für amd64 und arm64 verfügbar.

Wenn für eine Installation keine Adresse angegeben ist, wird das Image aus dem Quellcode erstellt. Die dafür erforderliche Dockerfile-Datei befindet sich im Quellcode und ist dieselbe, mit der auch die öffentliche Installation erstellt wird. Ab Version 1.3.21.

Bedingungen

• Eine Umgebung, in der Container auf AMD64 oder ARM64 ausgeführt werden können;
• Ausgehende HTTPS-Verbindungen zu den angebotenen Quellplattformen, siehe Bronnen;
• Ein Datenträger für den Datenordner: Protokoll, Exporte und gegebenenfalls das Zertifikat;
• Optional PostgreSQL 18, wenn die Einstellungen und das Protokoll in einer Datenbank statt in Dateien gespeichert werden sollen. Ab Version 1.3.51; bis einschließlich 1.3.50 war dies PostgreSQL 17. Eine bestehende Datenbank aus Version 17 wird nicht automatisch übernommen, siehe Uitrol en Beheer.

Mit docker-compose.production.yml

Das Repository stellt „docker-compose.production.yml“ bereit. Diese Konfiguration geht davon aus, dass Caddy selbst ebenfalls in einem Container läuft und die TLS-Verschlüsselung übernimmt; der Dienst selbst veröffentlicht dann keinen eigenen Port auf dem Host. Eine grafische Darstellung dieser Konfiguration finden Sie unter Uitrol en Beheer.

• Richten Sie einmalig das freigegebene Netzwerk ein, über das Caddy und der Dienst miteinander kommunizieren können: docker network create proxy.
• Erstellen Sie neben der Compose-Datei eine Datei „.env“ mit mindestens drei Passwörtern: BBN_INSTALL_PASSWORD (die Rolle, die das Datenmodell erstellt und aktualisiert), BBN_WEB_PASSWORD (die Rolle, unter der der Dienst läuft) und BBN_ADMIN_PASSWORD (die Verwaltungskonsole; ohne diese weigert sich der Dienst, zu starten). BBN_INSTALL_USER, BBN_WEB_USER, BBN_ADMIN_USER, BBN_DATABASE sowie BBN_PROJECT sind optional und haben einen Standardwert. Wie sich ein solcher .env-Name zu einer Einstellung des Dienstes selbst verhält, ist unter Instellingen Overschrijven beschrieben.
• Starten Sie den Dienst und die Datenbank:

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

• Wenn neben dieser Umgebung eine zweite Umgebung auf demselben Server läuft, beispielsweise eine Testumgebung, erhält diese eine eigene „.env“ mit eigenen Adressen „BBN_PROJECT“ und „BBN_ENVIRONMENT=Test“. Beide werden über dieselbe „compose“-Datei ausgeführt; Informationen zur Namensgebung finden Sie in der Erläuterung am Anfang dieser Datei.
• Auf eine neue Version aktualisieren:

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

Unter Uitrol en Beheer erfahren Sie, wie sich dies auf das Datenmodell auswirkt und welche Schritte bei einer Hauptversion von PostgreSQL zu beachten sind.

Die Schritte

• Laden Sie das Container-Image herunter oder erstellen Sie es aus dem Quellcode, falls keine Adresse bekannt ist. Die Befehle zum Starten des Dienstes und der Datenbank finden Sie weiter oben unter „Mit docker-compose.production.yml“.
• Legen Sie das Administratorpasswort fest. Ab Version 1.3.21 enthält das Image kein Standardpasswort mehr und der Dienst lässt sich ohne festgelegtes Passwort nicht starten. Es wird unter BesluitBron:Admin:Password angegeben, in der empfohlenen Konfiguration aus BBN_ADMIN_PASSWORD in der Datei „.env“. Bis zum 1.3.21 startete der Dienst mit einem öffentlichen Standardpasswort, woraufhin die Konsole eine Warnung anzeigte.
• Stellen Sie die öffentliche Adresse ein. Die angezeigten MCP-Adressen und die Exportverweise verweisen dann auf die eigene Installation statt auf BesluitBron.nl.
• Wählen Sie aus, welche Quellen angeboten werden sollen. Jede Quelle verfügt über einen eigenen Schalter; mindestens einer muss eingeschaltet bleiben, siehe Connectorregister.
• Fügen Sie TLS davor ein. In der empfohlenen Konfiguration übernimmt ein Reverse-Proxy die TLS-Terminierung, und der Container kommuniziert innerhalb des eigenen Netzwerks ganz normal über HTTP, siehe Uitrol en Beheer.
• Geben Sie unter „BesluitBron:Organisation“ die Daten des Installateurs ein: Name, Adresse, E-Mail-Adresse und Registrierungsnummer. Solange die Felder für Name und E-Mail-Adresse leer sind, zeigt die Website weder ein Impressum noch Organisationsdaten an, da ein unvollständig ausgefülltes Impressum wie eine Antwort wirkt. Ab Version 1.3.7.
• Fügen Sie BesluitBron:Organisation:Logo in Ihr eigenes Logo ein, sofern Ihre Organisation über ein solches verfügt. Dabei kann es sich um eine vollständige Adresse auf Ihrer eigenen Website oder um einen Pfad zu einer Datei unter wwwroot handeln. Das Logo wird nicht auf dem Bildschirm angezeigt: Es ist Teil der maschinenlesbaren Daten jeder öffentlichen Seite, anhand derer eine Suchmaschine erkennt, wer die Website betreibt. Das Feld kann leer gelassen werden; in diesem Fall wird kein Logo veröffentlicht. Ab Version 1.3.21.
• Geben Sie BesluitBron:Donation ein, wenn die Installation um einen Beitrag bittet, und lassen Sie das Feld leer, wenn dies nicht der Fall ist. Solange Iban leer ist, erscheint kein Spenden-Button in der Leiste, es öffnet sich kein Fenster und die Adresse /nl/doneren existiert nicht. Geben Sie außerdem unter „BeneficiaryName“ den Namen des Kontoinhabers und unter „Reference“ den Verwendungszweck ein, den ein Spender angibt. „SmallPrint“ ist der eigene Schlusssatz unter dem Fenster, beispielsweise zur Steuerabzugsfähigkeit und darüber, wohin das Geld fließt; dieser Text wird unverändert angezeigt und nicht übersetzt. Ab Version 1.3.29.
• Erstellen Sie die QR-Codes nach der Änderung des Kontos erneut mit tools/make-epc-qr.py und richten Sie BesluitBron:Donation:QrIban auf dasselbe Konto ein. Das Fenster zeigt die Codes nur so lange an, wie diese beiden identisch sind. Niemand überprüft einen QR-Code nachträglich, und ein Code aus einer früheren Installation ist nicht von einem gültigen zu unterscheiden, obwohl er das Geld an einen anderen Empfänger weiterleitet. Ab Version 1.3.29.
• Geben Sie BesluitBron:Donation:PaymentFormUrl als Adresse des Zahlungsbildschirms des Spenden-Dienstes ein, sofern vorhanden, und fügen Sie dieselbe Adresse unter BesluitBron:Security:FrameSources hinzu. Ohne diesen zweiten Schritt blockiert der Browser das Fenster. Bleibt das Feld leer, bietet das Fenster nur die Überweisung an, und das ist eine voll funktionsfähige Konfiguration. Ab Version 1.3.29.
• Verweisen Sie BesluitBron:Support:ForumUrl auf die eigene Seite für Fragen und Probleme oder lassen Sie das Feld leer. Bleibt der Standardwert bestehen, verweist die Installation ihre Nutzer auf das Forum des Entwicklers, siehe Contact en Meldingen. Ab Version 1.3.7.
• Geben Sie „BesluitBron:Distribution:ImageReference“ nur ein, wenn diese Installation selbst ein Image bereitstellt oder eines spiegelt, und zwar mit der Adresse ohne Tag. Die Seite „Selbst ausführen“ zeigt dann den Befehl zum Abrufen an, wobei die laufende Version als Tag angegeben wird. Bleibt das Feld leer, wird auf dieser Seite nur der Quellcode aufgeführt. Unter RegistryOperator ist angegeben, wer diese Registry betreibt; dies wird beim Befehl angezeigt. Ab Version 1.3.21.
• Lassen Sie „BesluitBron:Mcp“ unverändert, es sei denn, ein Client erhält eine Ablehnung, die niemand erklären kann. Der Dienst speichert 30 Minuten lang, auf welchem Connector eine MCP-Sitzung geöffnet ist – gerechnet ab der letzten Anfrage dieser Sitzung – und nutzt diese Information, um einen Client abzuweisen, der danach einen anderen Connector anspricht. SessionBindingRetentionMinutes ändert diese 30 Minuten. Ab Version 1.3.7.
• Geben Sie „BesluitBron:Mail“ ein, wenn die Website Nachrichten versenden können soll: das Gateway, den Port, den Benutzernamen, das Passwort und eine Absenderadresse, die von diesem Gateway verifiziert wurde. Ist „Enabled“ deaktiviert, fordert die Daumen-Schaltfläche auf den öffentlichen Seiten keine Nachricht an, da eine Nachricht, die nirgendwo ankommt, nicht angefordert werden sollte. Ab Version 1.3.34.
• Eine Datenbank ist erforderlich, und der Dienst startet ohne diese nicht. Bis einschließlich Version 1.3.72 galt dies nur für einen Teil der Funktionen, wie beispielsweise das Versenden von Nachrichten: Die Warteschlange dafür ist eine Tabelle, sodass ohne Datenbank nichts versendet wurde, die Daumen-Schaltfläche keine Nachricht anforderte und die Test-Schaltfläche deaktiviert war. Ab Version 1.3.73 weigert sich der Dienst, ohne Datenbank zu starten, und gibt dabei an, welches der drei Elemente fehlt: der Schalter, die Verbindung zum Datenmodell oder die Verbindung zum Dienst selbst.
• Überprüfen Sie diese Einstellungen mit der Schaltfläche „Testnachricht senden“ auf dem Bildschirm „Einstellungen“ der Verwaltungskonsole. Die Nachricht wird an die Adresse unter BesluitBron:Organisation:Email gesendet und an keine andere Adresse. Sie landet zunächst in der Warteschlange; aktualisieren Sie die Seite, um zu sehen, was das Gateway dazu gemeldet hat. Sollte dies nicht funktionieren, wird angezeigt, was das Gateway selbst zurückgemeldet hat, beispielsweise dass die Verbindung abgelehnt wurde oder dass die Anmeldung fehlgeschlagen ist. „Gesendet“ bedeutet, dass das Gateway die Nachricht angenommen hat, sagt aber nichts darüber aus, ob sie zugestellt wurde. Ab Version 1.3.34.
• Lassen Sie „BesluitBron:Corpus“ unverändert, es sei denn, die Installation darf keine ausgehenden Aufrufe tätigen. Diese Einstellungen legen fest, wie der Umfang jeder Quelle für das Diagramm auf der Startseite gemessen wird: IntervalHours steht für einen Tag, Enabled deaktiviert die Messung, MaximumShrinkPercent ist der Schwellenwert, unterhalb dessen ein Ergebnis abgelehnt wird (ein Fünftel), und TimeoutSeconds gibt an, wie viel eine Plattform kosten darf. IntervalHours kann nur nach oben angepasst werden: Ein Wert unter 24 wird auf 24 erhöht. StatePath ist die Datei, in der der Server speichert, wann er zuletzt gemessen hat, standardmäßig ./data/corpus-size.json; ohne diese Datei misst er bei jedem Start neu, also lass sie im gemounteten Verzeichnis stehen. Die Datei kann entfernt werden: Das kostet eine zusätzliche Messung. Wenn die Messung deaktiviert ist, werden auf der Seite manuell ermittelte Werte angezeigt, zusammen mit dem Datum der jeweiligen Messung; daher kann die Funktion deaktiviert werden, ohne dass Daten verloren gehen. Siehe Startpagina. Ab Version 1.3.41.
• Sehen Sie unter /health nach, wo jeder angebotene Anschluss einzeln aufgeführt ist.

Zwei-Faktor-Authentifizierung

Jedes Konto in der Verwaltungskonsole erfordert eine Zwei-Faktor-Authentifizierung, auch das erste Konto. Nach der Einrichtung des Administratorpassworts fordert die Konsole bei der ersten Anmeldung dazu auf, eine Authentifizierungs-App zu verknüpfen, und zwar mithilfe eines QR-Codes und eines manuell eingegebenen Schlüssels. Anschließend werden zehn einmalig gültige Backup-Codes angezeigt; bewahren Sie diese an einem sicheren Ort auf. Ab Version 1.3.85.

Ein vergessenes Passwort kann der Kontoinhaber selbst zurücksetzen, und zwar über einen Link, der an die E-Mail-Adresse des Kontos gesendet wird. Geben Sie daher für jedes Konto eine E-Mail-Adresse an. Bei Verlust der Authentifizierungs-App oder der Backup-Codes ist ein Administrator erforderlich: Dieser setzt die Zwei-Faktor-Authentifizierung auf dem Bildschirm „Benutzer“ zurück, woraufhin der Kontoinhaber erneut einen Code erhält, um die Verknüpfung wiederherzustellen. Richten Sie „BesluitBron:Support:MfaResetPhoneNumber“ auf der Telefonnummer ein, unter der ein Kontoinhaber Hilfe erhalten kann; bei dieser Einrichtung wird die Nummer auf dem Anmeldebildschirm angezeigt.

Für das erste Konto, das außerhalb des Containers liegt, gibt es einen Wiederherstellungsweg für den Fall, dass das Passwort oder die Zwei-Faktor-Authentifizierung nicht mehr funktioniert. BesluitBron:BreakGlass:AllowedInitialLoginAddresses gibt an, von welcher Adresse oder Adressreihe die nächste Anmeldung nach einer solchen Wiederherstellung erfolgen darf; dieses Feld ist obligatorisch, sobald „BesluitBron:BreakGlass:Enabled“ aktiviert ist, da der Dienst sonst den Start verweigert. Ist dies eingestellt, erfolgt die Wiederherstellung durch das Ablegen einer leeren Datei „reset-password.trigger“ oder „reset-mfa.trigger“ im Ordner „break-glass“ unterhalb des Datenordners. Der Dienst stellt dies nur wieder her, wenn E-Mail eingerichtet ist und mindestens ein aktiver Administrator über eine E-Mail-Adresse verfügt, und benachrichtigt alle, wenn dies geschieht; ohne funktionierende E-Mail passiert nichts. Ab Version 1.3.86; bis einschließlich 1.3.85 war dieses Adressfeld optional und erlaubte bei einem leeren Wert jedem den Zugriff.

Das Anmelde-Cookie der Konsole ist eine Stunde lang gültig und wird bei jeder Aktion innerhalb dieser Stunde verlängert; nur echte Inaktivität beendet die Sitzung. Ab Version 1.3.86; bis einschließlich 1.3.85 betrug diese Dauer vierundzwanzig Stunden.

Für ein Skript, das automatisch Daten abruft, wie beispielsweise einen Dokumentations-Crawler, gibt es einen separaten Anmeldeweg. Dieser Weg funktioniert nur in einer Umgebung, die nicht „Production“ heißt, und nur bei einem Aufruf vom selben Gerät aus (localhost); ein Aufruf von einem anderen Ort aus wird abgelehnt, auch mit dem richtigen Schlüssel. Setzen Sie „BesluitBron:Automation:ApiKey“ auf einen Schlüssel, um den Weg freizugeben; bleibt dieses Feld leer, bleibt der Weg in jeder Umgebung gesperrt. Das Skript übermittelt diesen Schlüssel im Header „X-Automation-Api-Key“. Damit erstellt es sein eigenes Konto, richtet seine eigene Zwei-Faktor-Authentifizierung ein und meldet sich so oft wie nötig an. Anschließend löscht das Skript das Konto selbst wieder. Diese fünf Adressen sind in einer Umgebung, die nicht „Production“ heißt, auch in der Übersicht unter /api aufgeführt, siehe Swagger. Ab Version 1.3.86.

Nach der Installation

Richten Sie einen Assistenten gemäß Claude Aansluiten ein, wobei Sie anstelle von „BesluitBron.nl“ Ihre eigene Adresse verwenden. Legen Sie anschließend eine Aufbewahrungsfrist für den Datenordner fest, siehe Logging en Verantwoording.

Einschränkungen

• Eine geänderte Bronalschaltung wird beim Start angewendet. Eine Änderung erfordert daher einen Neustart;
• Die MCP-Adressen sehen keine Authentifizierung vor. Wer dies innerhalb seiner eigenen Umgebung anders handhaben möchte, kann dies im Netzwerk oder im Reverse-Proxy einrichten, siehe Openbaarheid en Persoonsgegevens.