bosa/opendata-best-webapi repository overview

Self-contained version of the Best-Address API + the latest address database, containing the addresses of all 3 Regions in Belgium with their geographic position (Lambert72, Lambert2008 and WGS84/GPS).

⁠Running the docker image

Provided for free "as-is", use at you own risk. Current configuration is tuned for 7 vCPU and 8 GB RAM, though 2 vCPU and 4 GB RAM might be sufficient for internal use.

This runs the container and exposes the API on port 8080

docker run -p 8080:8080 bosa/opendata-best-webapi

Test it with e.g. curl:

curl http://localhost:8080/belgianAddress/v2/municipalities

⁠(Optional) Verifying the integrity of the image

(Subject to change)

The public key can be downloaded from https://opendata.bosa.be/download/best/bestinabox/bestinabox-pub.key⁠

Images are signed with the open source Sigstore cosign⁠,but without using the public transparency log.

Execute the following command and verify that the exit code is 0 (success):

cosign verify --insecure-ignore-tlog=true --key bestinabox-pub.key bosa/opendata-best-webapi

⁠(Optional) Tuning for more or less CPU / memory

The included configuration is tuned for 7 vCPU and 8 GB RAM, but it is possible to increase/decrease the memory and vCPU settings using PGOPTIONS.

Using more than 12 GB memory will probably not make a difference in performance (as the whole database will eventually end up in memory), adding more vCPU might improve performance when serving many concurrent clients/requests.

Create a file bestinabox.env to store the postgres runtime option.

E.g., a configuration for 5 vCores (minus 1 for the Java application) and 4 GB (minus 1 GB for the application) might look like:

PGOPTIONS=-o "--max-worker-processes=4" -o "--max-parallel-workers=4" -o "--max-parallel-workers-per-gather=2" -o "--max-parallel-maintenance-workers=2" -o "--work-mem=5MB" -o "--maintenance-work-mem=256MB" -o "--effective-cache-size=3GB" -o "--shared-buffers=1GB"

Then run docker run -p 8080:8080 --env-file bestinabox.env bosa/opendata-best-webapi

⁠(Optional) Enabling HTTPS

If you want to use HTTPS instead of HTTP, you'll have to obtain (or generate your own) TLS certificate and private key.

Create a file bestinabox.env to store the docker environments variables

SPRING_SSL_BUNDLE_PEM_SERVER_KEYSTORE_CERTIFICATE=/home/best/tls/bestinabox.crt
SPRING_SSL_BUNDLE_PEM_SERVER_KEYSTORE_PRIVATE-KEY=/home/best/tls/bestinabox.key
SERVER_PORT=8443
SERVER_SSL_BUNDLE=server

Store the certificate as bestinabox.crt and the private key as bestinabox.key in a separate directory (e.g. /etc/tls/bestinabox, and mount the docker volume /home/best/tls

docker run -p 8443:8443 -v /etc/tls/bestinabox:/home/best/tls --env-file bestinabox.env bosa/opendata-best-webapi

⁠In OpenShift 4.x

Currently the container needs to run as the (fixed) userID 1000800026.

This can be set in the securityContext of the OpenShift Deployment YAML

spec:
  metadata:
    spec:
      securityContext:
        runAsUser: 1000800026

⁠Updates

By design, the image does not contain a mechanism to update the address database or the components of the web API.

Simply pull a new version (or latest) of the image to get the latest version of the web API and the address database.

⁠Swagger/OpenAPI:

The docker image contains an OpenAPI YAML file:

http://localhost:8080/belgianAddress/v2/doc/openapi.yaml

⁠Licenses

This image uses several open source components, including SpringBoot, Postgresql and PostGIS.

A complete list of the components and their respective licenses can be found on http://localhost:8080/belgianAddress/v2/doc/licenses/index.html

The address data is provided by the 3 Regions of Belgium, licensed under the Creative Commons Attribution 4.0 license.

⁠Contact

Please contact [email protected]⁠ if you're interested in using this application.

See also https://opendata.bosa.be⁠