Installatie

BesluitBron draait als openbare dienst op besluitbron.nl en hoeft voor gewoon gebruik niet te worden geïnstalleerd. Een eigen installatie is aan de orde wanneer het verkeer binnen het eigen netwerk moet blijven. Zij is ook aan de orde wanneer de organisatie zelf wil bepalen welke bronnen worden aangeboden. De publieke pagina "Zelf draaien" noemt de afwegingen; deze pagina beschrijft de handeling.

De software is beschikbaar onder de EUPL-1.2.

De software ophalen

De broncode wordt op aanvraag verstrekt via het e-mailadres op de contactpagina. Een aanvraag wordt binnen twee werkdagen beantwoord. Er is nog geen publieke repository; het colofon noemt de reden.

Het container-image komt van een registry buiten deze site. Het adres staat op de publieke pagina "Zelf draaien", met de opdracht om het op te halen en met de versie die deze installatie draait als tag. Die pagina toont het adres alleen wanneer de beheerder het heeft ingevuld onder BesluitBron:Distribution:ImageReference; het image is er voor amd64 en arm64.

Noemt een installatie geen adres, dan wordt het image uit de broncode gebouwd. De Dockerfile daarvoor zit in de broncode en is dezelfde waarmee de openbare installatie wordt gebouwd. Vanaf versie 1.3.21.

Voorwaarden

• Een omgeving die containers kan draaien, op amd64 of arm64;
• Uitgaande HTTPS-verbindingen naar de bronplatformen die worden aangeboden, zie Bronnen;
• Een schijfvolume voor de gegevensmap: verzoeklogboek, exports en eventueel het certificaat;
• Optioneel PostgreSQL 18, wanneer de instellingen en het logboek in een database horen in plaats van in bestanden. Vanaf versie 1.3.51; tot en met 1.3.50 was dat PostgreSQL 17. Een bestaande database van 17 gaat niet vanzelf mee, zie Uitrol en Beheer.

Met docker-compose.production.yml

Het repository levert docker-compose.production.yml. Die opstelling gaat ervan uit dat Caddy zelf ook in een container draait en de TLS voor haar rekening neemt; de dienst zelf publiceert dan geen eigen poort op de host. Zie Uitrol en Beheer voor die opstelling in beeld.

• Maak eenmalig het gedeelde netwerk aan waarop Caddy en de dienst elkaar bereiken: docker network create proxy.
• Maak een .env naast het composebestand, met ten minste drie wachtwoorden: BBN_INSTALL_PASSWORD (de rol die het datamodel aanmaakt en bijwerkt), BBN_WEB_PASSWORD (de rol waarmee de dienst draait) en BBN_ADMIN_PASSWORD (de beheerconsole; zonder deze weigert de dienst te starten). BBN_INSTALL_USER, BBN_WEB_USER, BBN_ADMIN_USER, BBN_DATABASE en BBN_PROJECT zijn optioneel en hebben een standaardwaarde. Hoe zo'n .env-naam zich verhoudt tot een instelling van de dienst zelf staat in Instellingen Overschrijven.
• Start de dienst en de database:

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

• Draait er een tweede omgeving naast deze op dezelfde server, bijvoorbeeld een testomgeving, dan krijgt die een eigen .env met een eigen BBN_PROJECT en BBN_ENVIRONMENT=Test. Beide draaien vanaf hetzelfde composebestand; zie de toelichting bovenaan dat bestand voor de naamgeving.
• Bijwerken naar een nieuwe versie:

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

Zie Uitrol en Beheer voor wat daarbij met het datamodel gebeurt, en voor de stappen bij een hoofdversie van PostgreSQL.

De stappen

• Haal het container-image op, of bouw het uit de broncode wanneer geen adres bekend is. De opdrachten om de dienst en de database te starten staan hierboven, onder "Met docker-compose.production.yml".
• Stel het beheerderswachtwoord in. Vanaf 1.3.21 levert het image geen standaardwachtwoord mee en weigert de dienst te starten zonder ingesteld wachtwoord. Het wordt meegegeven onder BesluitBron:Admin:Password, in de aanbevolen opstelling uit BBN_ADMIN_PASSWORD in de .env. Tot 1.3.21 startte de dienst met een openbaar standaardwachtwoord waarover de console een waarschuwing toonde.
• Stel het publieke adres in. De getoonde MCP-adressen en de exportverwijzingen wijzen dan naar de eigen installatie in plaats van naar besluitbron.nl.
• Kies welke bronnen worden aangeboden. Elke bron heeft een eigen schakelaar; ten minste één blijft aan, zie Connectorregister.
• Zet TLS ervoor. In de aanbevolen opstelling verzorgt een omgekeerde proxy de TLS-terminatie en spreekt de container gewoon HTTP binnen het eigen netwerk, zie Uitrol en Beheer.
• Vul in wie de installatie voert, onder BesluitBron:Organisation: naam, adres, e-mailadres en inschrijfnummer. Zolang naam en e-mailadres leeg zijn, toont de site geen colofon en geen organisatiegegevens, want een half ingevuld colofon lijkt een antwoord. Vanaf versie 1.3.7.
• Zet BesluitBron:Organisation:Logo op het eigen beeldmerk, als de organisatie er een heeft. Dat mag een volledig adres op de eigen website zijn, of een pad naar een bestand in wwwroot. Het logo staat niet op het scherm: het gaat mee in de machineleesbare gegevens van elke publieke pagina, waarmee een zoekmachine ziet wie de site uitgeeft. Leeg laten kan; dan wordt er geen logo gepubliceerd. Vanaf versie 1.3.21.
• Vul BesluitBron:Donation in wanneer de installatie om een bijdrage vraagt, en laat het leeg wanneer zij dat niet doet. Zolang Iban leeg is, staat er geen doneerknop in de balk, opent er geen venster en bestaat het adres /nl/doneren niet. Vul verder BeneficiaryName met de naam waarop de rekening staat en Reference met de omschrijving die een donateur meegeeft. SmallPrint is de eigen slotzin onder het venster, bijvoorbeeld over aftrekbaarheid en over waar het geld heen gaat; die tekst wordt getoond zoals hij er staat en wordt niet vertaald. Vanaf versie 1.3.29.
• Maak de QR-codes opnieuw na het wijzigen van de rekening, met tools/make-epc-qr.py, en zet BesluitBron:Donation:QrIban op diezelfde rekening. Het venster toont de codes alleen zolang die twee gelijk zijn. Niemand leest een QR-code na, en een code van een vorige installatie is niet van een goede te onderscheiden terwijl hij het geld ergens anders heen stuurt. Vanaf versie 1.3.29.
• Zet BesluitBron:Donation:PaymentFormUrl op het adres van het betaalscherm van de donatiedienst, als die er is, en voeg datzelfde adres toe aan BesluitBron:Security:FrameSources. Zonder die tweede stap blokkeert de browser het venster. Blijft de instelling leeg, dan biedt het venster alleen de overboeking, en dat is een volledige werkende opstelling. Vanaf versie 1.3.29.
• Wijs BesluitBron:Support:ForumUrl naar de eigen plek voor vragen en issues, of laat de instelling leeg. Blijft de standaardwaarde staan, dan verwijst de installatie haar gebruikers naar het forum van de maker, zie Contact en Meldingen. Vanaf versie 1.3.7.
• Vul BesluitBron:Distribution:ImageReference alleen in wanneer deze installatie zelf een image uitlevert of er een spiegelt, met het adres zonder tag. De pagina "Zelf draaien" toont dan de opdracht om het op te halen, met de draaiende versie als tag. Blijft de instelling leeg, dan noemt die pagina alleen de broncode. RegistryOperator noemt wie die registry voert en wordt bij de opdracht getoond. Vanaf versie 1.3.21.
• Laat BesluitBron:Mcp staan zoals het staat, tenzij een client een weigering krijgt die niemand kan verklaren. De dienst onthoudt dertig minuten lang op welke connector een MCP-sessie is geopend, geteld vanaf het laatste verzoek van die sessie, en gebruikt dat om een client te weigeren die daarna een andere connector aanspreekt. SessionBindingRetentionMinutes verandert die dertig minuten. Vanaf versie 1.3.7.
• Vul BesluitBron:Mail in wanneer de site berichten moet kunnen versturen: de gateway, de poort, de gebruikersnaam, het wachtwoord en een afzenderadres dat die gateway heeft geverifieerd. Staat Enabled uit, dan vraagt de duimknop op de publieke pagina's niet om een bericht, want een bericht dat nergens aankomt hoort niet te worden gevraagd. Vanaf versie 1.3.34.
• Een database is vereist en de dienst start er niet zonder. Tot en met versie 1.3.72 gold dat alleen voor een deel van de functies, zoals het versturen van berichten: de wachtrij daarvoor is een tabel, dus zonder database werd er niets verstuurd, vroeg de duimknop niet om een bericht en stond de testknop uit. Vanaf versie 1.3.73 weigert de dienst zonder database te starten, en zegt daarbij welk van de drie dingen ontbreekt: de schakelaar, de verbinding voor het datamodel of de verbinding voor de dienst zelf.
• Controleer die instellingen met de knop "Testbericht versturen" op het scherm Instellingen van de beheerconsole. Het bericht gaat naar het adres in BesluitBron:Organisation:Email en naar geen ander adres. Het komt eerst op de wachtrij; ververs de pagina om te zien wat de gateway ervan zei. Lukt het niet, dan staat er wat de gateway zelf terugmeldde, bijvoorbeeld dat de verbinding werd geweigerd of dat het aanmelden mislukte. Verstuurd zegt dat de gateway het bericht heeft aangenomen, en niets over of het is bezorgd. Vanaf versie 1.3.34.
• Laat BesluitBron:Corpus staan zoals het staat, tenzij de installatie geen uitgaande aanroepen mag doen. Deze instellingen bepalen hoe de omvang van elke bron wordt gemeten voor de grafiek op de startpagina: IntervalHours is een dag, Enabled zet de meting uit, MaximumShrinkPercent is de grens waaronder een uitkomst wordt geweigerd (een vijfde) en TimeoutSeconds is wat één platform mag kosten. IntervalHours kan alleen omhoog: een waarde onder 24 wordt verhoogd naar 24. StatePath is het bestand waarin de server onthoudt wanneer hij voor het laatst heeft gemeten, standaard ./data/corpus-size.json; zonder dat bestand meet hij bij elke start opnieuw, dus laat het onder de gemounte map staan. Het bestand mag weg: dat kost één extra meting. Met de meting uit staan er cijfers op de pagina die met de hand zijn gemeten, met de datum van die meting erbij, dus uitzetten kan zonder dat er iets wegvalt. Zie Startpagina. Vanaf versie 1.3.41.
• Controleer /health, dat elke aangeboden connector afzonderlijk meldt.

Tweefactorauthenticatie

Elk account van de beheerconsole heeft tweefactorauthenticatie nodig, ook het eerste account. Na het instellen van het beheerderswachtwoord vraagt de console bij de eerste aanmelding om een authenticator-app te koppelen, met een QR-code en een handmatige sleutel. Daarna toont zij tien back-upcodes, eenmalig; bewaar ze op een veilige plek. Vanaf versie 1.3.85.

Een vergeten wachtwoord stelt een accounthouder zelf opnieuw in, met een koppeling die naar het e-mailadres van het account wordt gestuurd. Vul daarom een e-mailadres in bij elk account. Een verloren authenticator-app of verloren back-upcodes vraagt om een beheerder: die reset de tweefactorauthenticatie op het scherm "Gebruikers", waarna de accounthouder opnieuw een code krijgt toegestuurd om de koppeling te herstellen. Zet BesluitBron:Support:MfaResetPhoneNumber op het telefoonnummer waar een accounthouder daarvoor terechtkan; deze installatie toont het nummer op het aanmeldscherm.

Voor het eerste account, van buiten de container, bestaat een herstelpad voor het geval het wachtwoord of de tweefactorauthenticatie niet meer werkt. BesluitBron:BreakGlass:AllowedInitialLoginAddresses noemt van welk adres of welke adresreeks de eerstvolgende aanmelding na zo'n herstel mag komen; dit veld is verplicht zodra BesluitBron:BreakGlass:Enabled aan staat, want de dienst weigert anders te starten. Is dat ingesteld, dan wordt hersteld door een leeg bestand reset-password.trigger of reset-mfa.trigger te plaatsen in de map break-glass onder de gegevensmap. De dienst herstelt dit alleen wanneer e-mail is ingesteld en ten minste één actieve beheerder een e-mailadres heeft, en waarschuwt hen allemaal wanneer het gebeurt; zonder werkende e-mail gebeurt er niets. Vanaf versie 1.3.86; tot en met 1.3.85 was dit adresveld optioneel en liet een lege waarde iedereen toe.

De aanmeldcookie van de console is een uur geldig, oplopend bij elke handeling binnen dat uur; alleen echte inactiviteit beëindigt de sessie. Vanaf versie 1.3.86; tot en met 1.3.85 was dit vierentwintig uur.

Voor een script dat automatisch gegevens ophaalt, zoals een documentatie-crawler, bestaat een aparte aanmeldweg. Die weg werkt alleen op een omgeving die niet Production heet, en alleen voor een aanroep vanaf hetzelfde toestel (localhost); een aanroep van elders wordt geweigerd, ook met de juiste sleutel. Zet BesluitBron:Automation:ApiKey op een sleutel om de weg te openen; blijft dat veld leeg, dan blijft de weg gesloten, op elke omgeving. Het script stuurt die sleutel mee in de kop X-Automation-Api-Key. Daarmee maakt het zijn eigen account aan, koppelt het zijn eigen tweefactorauthenticatie, en meldt het zich zo vaak aan als nodig is. Na afloop verwijdert het script het account weer zelf. Deze vijf adressen staan, op een omgeving die niet Production heet, ook in het overzicht op /api, zie Swagger. Vanaf versie 1.3.86.

Na de installatie

Sluit een assistent aan volgens Claude Aansluiten, met het eigen adres in plaats van besluitbron.nl. Bepaal daarna een bewaartermijn voor de gegevensmap, zie Logging en Verantwoording.

Beperkingen

• Een gewijzigde bronschakeling wordt bij het starten toegepast. Een wijziging vraagt dus een herstart;
• De MCP-adressen kennen geen authenticatie. Wie dat binnen de eigen omgeving anders wil, regelt dat in het netwerk of in de omgekeerde proxy, zie Openbaarheid en Persoonsgegevens.