For council members For journalists Connect Claude First use Explorer Not connected Status Search without AI
Search without AI For council members For journalists Connect Claude Dossiers First use

Explorer

Officiële Bekendmakingen Open Raadsinformatie OpenBesluitvorming OpenTK Rechtspraak Tweede Kamer Not connected Documentation
BesluitBron 1.4.4-23
English ▾
Dutch (Nederlands) English German (Deutsch) French (Français)
Status Sign in

Installation

Last changed on .

BesluitBron operates as a public service at besluitbron.nl and does not need to be installed for normal use. An on-premises installation is required when traffic must remain within the organisation’s own network. It is also required when the organisation wishes to determine for itself which sources are made available. The public page ‘Run it yourself’ outlines the considerations; this page describes the procedure.

The software is available under the EUPL 1.2.

Downloading the software

The source code is provided on request via the email address on the contact page. Requests will be answered within two working days. There is no public repository as yet; the reason is stated in the colophon.

The container image comes from a registry outside this site. The address is listed on the public page ‘Run it yourself’, along with instructions on how to fetch it and the version currently running on this installation as a tag. That page only displays the address if the administrator has entered it under BesluitBron:Distribution:ImageReference; the image is available for amd64 and arm64.

If an installation does not specify an address, the image is built from the source code. The Dockerfile for this is included in the source code and is the same one used to build the public installation. From version 1.3.21 onwards.

Terms and Conditions

  • An environment capable of running containers, on amd64 or arm64;
  • Outgoing HTTPS connections to the source platforms provided; see Bronnen;
  • A disk volume for the data folder: request log, exports and, if applicable, the certificate;
  • Optional PostgreSQL 18, when the settings and log should be stored in a database rather than in files. From version 1.3.51 onwards; up to and including 1.3.50, this was PostgreSQL 17. An existing PostgreSQL 17 database will not be migrated automatically; see Uitrol en Beheer.

Using docker-compose.production.yml

The repository provides docker-compose.production.yml. This configuration assumes that Caddy itself is also running in a container and handles the TLS; the service itself does not publish its own port on the host. See Uitrol en Beheer for a visual representation of this configuration.

  • Set up the shared network once, so that Caddy and the service can communicate with each other: docker network create proxy.
  • Create a .env file alongside the compose file, containing at least three passwords: BBN_INSTALL_PASSWORD (the role that creates and updates the data model), BBN_WEB_PASSWORD (the role under which the service runs) and BBN_ADMIN_PASSWORD (the management console; without this, the service will refuse to start). BBN_INSTALL_USER, BBN_WEB_USER, BBN_ADMIN_USER, BBN_DATABASE and BBN_PROJECT are optional and have a default value. How such a .env name relates to a setting within the service itself is explained at Instellingen Overschrijven.
  • Start the service and the database:
docker compose -f docker-compose.production.yml up -d
  • If a second environment is running alongside this one on the same server – for example, a test environment – it will be assigned its own .env with its own BBN_PROJECT and BBN_ENVIRONMENT=Test. Both run from the same compose file; see the notes at the top of that file for details on naming conventions.
  • Updating to a new version:
docker compose -f docker-compose.production.yml pull
docker compose -f docker-compose.production.yml up -d

See Uitrol en Beheer for details of what happens to the data model in this context, and for the steps involved in a major release of PostgreSQL.

The steps

  • Fetch the container image, or build it from the source code if no URL is available. The commands to start the service and the database are listed above, under “Using docker-compose.production.yml”.
  • Set the administrator password. From version 1.3.21 onwards, the image no longer includes a default password and the service will refuse to start unless a password has been set. It is provided at BesluitBron:Admin:Password, in the recommended configuration from BBN_ADMIN_PASSWORD in the .env. Up to version 1.3.21, the service started with a public default password, for which the console displayed a warning.
  • Set the public address. The MCP addresses displayed and the export links will then point to your own installation rather than to BesluitBron.nl.
  • Select which sources are to be made available. Each source has its own switch; at least one must remain switched on – see Connectorregister.
  • Set TLS first. In the recommended configuration, a reverse proxy handles TLS termination and the container simply communicates via HTTP within its own network; see Uitrol en Beheer.
  • Enter the details of the organisation carrying out the installation under ‘BesluitBron:Organisation’: name, address, email address and registration number. As long as the name and email address fields are left blank, the site will not display a colophon or organisational details, as a partially completed colophon might be mistaken for a response. From version 1.3.7 onwards.
  • Set BesluitBron:Organisation:Logo to the organisation’s own logo, if it has one. This can be a full address on the organisation’s own website, or a path to a file at wwwroot. The logo does not appear on screen: it is included in the machine-readable data of every public page, which allows a search engine to identify the site’s publisher. You can leave this field blank; in that case, no logo will be published. From version 1.3.21 onwards.
  • Enter BesluitBron:Donation when the installation asks for a contribution, and leave it blank if it does not. As long as Iban is left blank, there will be no donate button in the bar, no window will open, and the address /nl/doneren will not exist. Also, enter BeneficiaryName with the name on the account and Reference with the reference provided by the donor. SmallPrint is your own closing text below the window, for example regarding tax deductibility and where the money goes; this text is displayed exactly as it is entered and is not translated. From version 1.3.29 onwards.
  • Regenerate the QR codes after changing the account, using tools/make-epc-qr.py, and set BesluitBron:Donation:QrIban to that same account. The window will only display the codes as long as those two are the same. Nobody checks a QR code, and a code from a previous installation is indistinguishable from a valid one whilst it sends the money elsewhere. From version 1.3.29 onwards.
  • Enter BesluitBron:Donation:PaymentFormUrl as the address of the donation service’s payment screen, if one exists, and add that same address to BesluitBron:Security:FrameSources. Without this second step, the browser will block the window. If the setting is left blank, the window will only offer the bank transfer option, and that is a fully functional setup. From version 1.3.29 onwards.
  • Direct BesluitBron:Support:ForumUrl to the appropriate location for queries and issues, or leave the setting blank. If the default value is retained, the installation will direct its users to the developer’s forum; see Contact en Meldingen. From version 1.3.7 onwards.
  • Only enter BesluitBron:Distribution:ImageReference if this installation itself serves an image or mirrors one, using the address without the tag. The ‘Run yourself’ page will then display the command to fetch it, with the running version as the tag. If the setting is left blank, that page will only list the source code. RegistryOperator specifies who maintains that registry and is displayed alongside the command. From version 1.3.21 onwards.
  • Leave ‘BesluitBron:Mcp’ as it is, unless a client receives a refusal that nobody can explain. The service retains information for thirty minutes about which connector an MCP session was opened on, counted from the last request of that session, and uses this to reject a client that subsequently attempts to connect to a different connector. SessionBindingRetentionMinutes changes that thirty-minute period. From version 1.3.7 onwards.
  • Enter BesluitBron:Mail if the site needs to be able to send messages: the gateway, the port, the username, the password and a sender address that has been verified by that gateway. If ‘Enabled’ is disabled, the thumbs-up button on the public pages will not prompt for a message, as a message that cannot be delivered should not be requested. From version 1.3.34 onwards.
  • A database is required, and the service will not start without one. Up to and including version 1.3.72, this only applied to some of the functions, such as sending messages: the queue for this is a table, so without a database, nothing was sent, the thumbs-up button did not prompt for a message and the test button was disabled. From version 1.3.73 onwards, the service refuses to start without a database, and indicates which of the three elements is missing: the switch, the connection for the data model or the connection for the service itself.
  • Check these settings using the “Send test message” button on the Settings screen of the management console. The message is sent to the address at BesluitBron:Organisation:Email and to no other address. It is placed in the queue first; refresh the page to see what the gateway reported. If it fails, the page will display the gateway’s response, for example, that the connection was refused or that the login failed. ‘Sent’ indicates that the gateway has accepted the message, but does not indicate whether it has been delivered. From version 1.3.34 onwards.
  • Leave BesluitBron:Corpus as it is, unless the installation must not make any outgoing calls. These settings determine how the size of each resource is measured for the graph on the home page: IntervalHours is one day, Enabled disables the measurement, MaximumShrinkPercent is the threshold below which an output is rejected (one-fifth) and TimeoutSeconds is the maximum cost allowed for a single platform. IntervalHours can only go up: a value below 24 is increased to 24. StatePath is the file in which the server records when it last took a measurement; by default, this is ./data/corpus-size.json. Without this file, it takes a new measurement on every start-up, so ensure it remains in the mounted directory. The file can be removed: this results in one extra measurement. With the measurement disabled, the page displays figures that have been measured manually, along with the date of that measurement, so you can disable it without losing any data. See Startpagina. From version 1.3.41 onwards.
  • Check /health, which lists each connector on offer individually.

Two-factor authentication

Every account on the management console requires two-factor authentication, including the first account. After setting the administrator password, the console will ask you to link an authenticator app when you log in for the first time, using a QR code and a manual key. It will then display ten one-off backup codes; keep these in a safe place. From version 1.3.85 onwards.

An account holder can reset a forgotten password themselves using a link sent to the account’s email address. You should therefore enter an email address for each account. A lost authenticator app or lost backup codes require an administrator: they can reset two-factor authentication on the ‘Users’ screen, after which the account holder will be sent a new code to restore the link. Set ‘BesluitBron:Support:MfaResetPhoneNumber’ to the telephone number that an account holder can use for this purpose; this setting will display the number on the login screen.

For the first account, accessed from outside the container, there is a recovery path in case the password or two-factor authentication stops working. BesluitBron:BreakGlass:AllowedInitialLoginAddresses specifies the address or range of addresses from which the next login following such a recovery must originate; this field is mandatory once ‘BesluitBron:BreakGlass:Enabled’ is enabled, as the service will otherwise refuse to start. Once this is configured, recovery is triggered by placing an empty file named ‘reset-password.trigger’ or ‘reset-mfa.trigger’ in the ‘break-glass’ folder within the data folder. The service will only restore this if email is configured and at least one active administrator has an email address, and will notify them all when this happens; without a working email service, nothing will happen. From version 1.3.86 onwards; up to and including 1.3.85, this address field was optional and an empty value allowed anyone to access it.

The console’s session cookie is valid for one hour, and is extended with every proceeding taken within that hour; only genuine inactivity terminates the session. From version 1.3.86 onwards; up to and including version 1.3.85, this was twenty-four hours.

For a script that automatically retrieves data, such as a documentation crawler, there is a separate authentication method. This method only works on an environment that is not labelled ‘Production’, and only for requests made from the same device (localhost); requests from elsewhere will be rejected, even with the correct key. Set BesluitBron:Automation:ApiKey to a key to enable this method; if that field remains empty, the method remains disabled in all environments. The script includes this key in the ‘X-Automation-Api-Key’ header. It uses this to create its own account, set up its own two-factor authentication, and log in as often as necessary. Once complete, the script deletes the account itself. These five addresses are also listed, on an environment not named ‘Production’, in the overview at /api; see Swagger. From version 1.3.86 onwards.

After installation

Set up an assistant as described at Claude Aansluiten, using your own address instead of BesluitBron.nl. Then set a retention period for the data folder; see Logging en Verantwoording.

Restrictions

  • A modified source configuration is applied on start-up. A change therefore requires a restart;
  • The MCP addresses do not require authentication. Anyone wishing to configure this differently within their own environment should do so in the network or in the reverse proxy; see Openbaarheid en Persoonsgegevens.