Docker Support

The VCDB is also available as a Docker image built on top of the official PostgreSQL and PostGIS Docker images. It is designed to closely mirror the behavior of the base images and the VCDB shell scripts. As a result, all configuration options available in the base images are also supported by the VCDB Docker image.

The VCDB Docker images for version >= 5.0 are only available for PostgreSQL/PostGIS and are exclusively compatible with the vcdb-tool images. See here for more information on CityGML version and VCDB tools compatibility.

TL;DR

  • Linux

  • Windows CMD

docker run --name vcdb -p 5432:5432 -d \
    -e POSTGRES_PASSWORD=<theSecretPassword> \
    -e SRID=<EPSG code> \
    [-e HEIGHT_EPSG=<EPSG code>] \
    [-e SRS_NAME=<mySrsName>] \
    [-e POSTGRES_DB=<database name>] \
    [-e POSTGRES_USER=<username>] \
    [-e POSTGIS_SFCGAL=<true|false|yes|no>] \
vcdb-pg[:TAG]
docker run --name vcdb -p 5432:5432 -d ^
    -e POSTGRES_PASSWORD=<theSecretPassword> ^
    -e SRID=<EPSG code> ^
    [-e HEIGHT_EPSG=<EPSG code>] ^
    [-e SRS_NAME=<mySrsName>] ^
    [-e POSTGRES_DB=<database name>] ^
    [-e POSTGRES_USER=<username>] ^
    [-e POSTGIS_SFCGAL=<true|false|yes|no>] ^
vcdb-pg[:TAG]

Get the VCDB Docker image

Using a pre-built image

Pre-built Docker images for each VCDB release are available as ZIP packages from our software download site. Each package includes the image file in .tar.gz format and a quick start guide to help you get up and running. After unzipping the package, load the image into your local Docker Engine with the following command:

docker load -i /path/to/vcdb-postgres-docker-image-<version>.tar.gz

By default, the Docker image is registered under the name vcdb-pg:<version>, where the release <version> is used as the image tag.

Building your own image

If you prefer to build the Docker image yourself, start by downloading the VCDB software ZIP package from our software download site. Once extracted, you will find a Dockerfile in the root directory. You can use this file as-is or modify it to meet your specific requirements.

The Dockerfile supports an optional build argument, BASEIMAGE_TAG, which allows you to specify the PostgreSQL/PostGIS base image to use for the VCDB Docker image. A full list of available tags can be found on Docker Hub. If BASEIMAGE_TAG is not provided, a default base image will be used.

To build the VCDB Docker image, run the following command.

  • Linux

  • Windows CMD

# Build using the default base image
docker build -t vcdb-pg .

# Build using a specific PostgreSQL/PostGIS base image tag
docker build . -t vcdb-pg \
    --build-arg BASEIMAGE_TAG=<TAG>
# Build using the default base image
docker build -t vcdb-pg .

# Build using a specific PostgreSQL/PostGIS base image tag
docker build . -t vcdb-pg ^
    --build-arg BASEIMAGE_TAG=<TAG>
Ensure to replace <TAG> with the desired version of the PostgreSQL/PostGIS base image, such as 17-3.5.

Usage and configuration

A VCDB container is configured by setting environment variables inside the container. This can be done using the -e VARIABLE=VALUE option with the docker run command.

The VCDB Docker image defines the environment variables SRID, HEIGHT_EPSG, SRS_NAME, and CHANGELOG for configuring the VCDB instance. Additional environment variables inherited from the base image provide further options for configuring the underlying PostgreSQL/PostGIS database.

The table below lists the most commonly used environment variables for setting up a VCDB container.

Environment variable Description

SRID

Specifies the Spatial Reference ID of the coordinate reference system (CRS) used for the VCDB instance. If not set, the VCDB instance will not be created, and the container will start as a plain PostgreSQL/PostGIS instance.

HEIGHT_EPSG

EPSG code of the vertical reference system. You may omit this value or set it to 0 (default) if unknown, or if SRID already defines a 3D system.

SRS_NAME

The OGC-compliant name of the CRS. This name is used, for example, when exporting data to CityGML or CityJSON formats. If not set, a default name is derived from the SRID and HEIGHT_EPSG values.

CHANGELOG

Set to yes to enable the changelog extension for the VCDB instance. Default is no.

POSTGRES_USER

Username for the VCDB database. Defaults to postgres.

POSTGRES_DB

Name of the VCDB database. If not set, defaults to the value of POSTGRES_USER.

POSTGRES_PASSWORD

Password for the VCDB database. This variable is mandatory.

POSTGIS_SFCGAL

Set to true to enable the PostGIS postgis_sfcgal extension, or false (default) to disable it.

PROJ_NETWORK

Enables downloading of coordinate transformation grid files. Due to changes in recent PostGIS base images, this should be set to on if you intend to perform coordinate transformations in the VCDB.
All variables besides POSTGRES_PASSWORD and SRID are optional.

Performance tuning

The configuration of the PostgreSQL database inside the VCDB container can significantly impact performance, particularly during import and export operations. PostgreSQL provides various configuration parameters that can enhance performance and enable features like query parallelization.

While database optimization is a complex topic, tools like PGTune can help you quickly generate a recommended set of configuration settings for your system to improve performance.

  1. Visit the PGTune website and fill out the form with your system parameters. PGTune will generate recommended settings for your system similar to those shown below:

    # DB Version: 13
# OS Type: linux
# DB Type: mixed
# Total Memory (RAM): 8 GB
# CPUs num: 8
# Connections num: 20
# Data Storage: ssd

max_connections = 20
shared_buffers = 2GB
effective_cache_size = 6GB
maintenance_work_mem = 512MB
checkpoint_completion_target = 0.9
wal_buffers = 16MB
default_statistics_target = 100
random_page_cost = 1.1
effective_io_concurrency = 200
work_mem = 13107kB
min_wal_size = 1GB
max_wal_size = 4GB
max_worker_processes = 8
max_parallel_workers_per_gather = 4
max_parallel_workers = 8
max_parallel_maintenance_workers = 4

  2. To apply the settings, pass them to the postgres command using the -c option when starting your VCDB container with docker run (see lines 4ff.).

    • Linux

    • Windows CMD

    docker run -d -i -t --name vcdb -p 5432:5342 \
    -e SRID=25832 \
    -e POSTGRES_PASSWORD=changeMe \
    vcdb-pg[:TAG] postgres \
    -c max_connections=20 \
    -c shared_buffers=2GB \
    -c effective_cache_size=6GB \
    -c maintenance_work_mem=512MB \
    -c checkpoint_completion_target=0.9 \
    -c wal_buffers=16MB \
    -c default_statistics_target=100 \
    -c random_page_cost=1.1 \
    -c effective_io_concurrency=200 \
    -c work_mem=13107kB \
    -c min_wal_size=1GB \
    -c max_wal_size=4GB \
    -c max_worker_processes=8 \
    -c max_parallel_workers_per_gather=4 \
    -c max_parallel_workers=8 \
    -c max_parallel_maintenance_workers=4
    docker run -d -i -t --name vcdb -p 5432:5342 ^
    -e SRID=25832 ^
    -e POSTGRES_PASSWORD=changeMe ^
    vcdb-pg[:TAG] postgres ^
    -c max_connections=20 ^
    -c shared_buffers=2GB ^
    -c effective_cache_size=6GB ^
    -c maintenance_work_mem=512MB ^
    -c checkpoint_completion_target=0.9 ^
    -c wal_buffers=16MB ^
    -c default_statistics_target=100 ^
    -c random_page_cost=1.1 ^
    -c effective_io_concurrency=200 ^
    -c work_mem=13107kB ^
    -c min_wal_size=1GB ^
    -c max_wal_size=4GB ^
    -c max_worker_processes=8 ^
    -c max_parallel_workers_per_gather=4 ^
    -c max_parallel_workers=8 ^
    -c max_parallel_maintenance_workers=4

Hints for highly parallel systems

If you’re running the VCDB Docker container on a server with many CPU cores, proper tuning can allow a high degree of query parallelization. However, highly parallel queries may cause PostgreSQL to exceed the available shared memory space.

To prevent this, it is recommended to increase the Docker shared memory allocation using the --shm-size option of the docker run command. Additionally, ensure that PostgreSQL’s shared_buffers setting is increased accordingly. Testing also shows that adjusting the max_locks_per_transaction parameter of PostgreSQL is important to achieve substantial performance improvements, especially under heavy workloads.

For example, assume the following system parameters and suggested configuration settings generated with PGTune.

# DB Version: 17
# OS Type: linux
# DB Type: dw
# Total Memory (RAM): 32 GB
# CPUs num: 16
# Connections num: 100
# Data Storage: ssd

max_connections = 100
shared_buffers = 8GB
effective_cache_size = 24GB
maintenance_work_mem = 2GB
checkpoint_completion_target = 0.9
wal_buffers = 16MB
default_statistics_target = 500
random_page_cost = 1.1
effective_io_concurrency = 200
work_mem = 36157kB
huge_pages = try
min_wal_size = 4GB
max_wal_size = 16GB
max_worker_processes = 16
max_parallel_workers_per_gather = 8
max_parallel_workers = 16
max_parallel_maintenance_workers = 4

A corresponding configuration of the VCDB Docker container including the --shm-size, shared_buffers, and max_locks_per_transaction parameters would look like this:

  • Linux

  • Windows CMD

docker run -d -i -t --name vcdb -p 5432:5342 \
    --shm-size=8g \
    -e SRID=25832 \
    -e POSTGRES_PASSWORD=changeMe \
    vcdb-pg[:TAG] postgres \
    -c max_connections=100 \
    -c shared_buffers=8GB \
    -c effective_cache_size=24GB \
    -c maintenance_work_mem=2GB \
    -c checkpoint_completion_target=0.9 \
    -c wal_buffers=16MB \
    -c default_statistics_target=500 \
    -c random_page_cost=1.1 \
    -c effective_io_concurrency=200 \
    -c work_mem=36157kB \
    -c huge_pages=try \
    -c min_wal_size=4GB \
    -c max_wal_size=16GB \
    -c max_worker_processes=16 \
    -c max_parallel_workers_per_gather=8 \
    -c max_parallel_workers=16 \
    -c max_parallel_maintenance_workers=4 \
    -c max_locks_per_transaction=1024
docker run -d -i -t --name vcdb -p 5432:5342 ^
    --shm-size=8g ^
    -e SRID=25832 ^
    -e POSTGRES_PASSWORD=changeMe ^
    vcdb-pg[:TAG] postgres ^
    -c max_connections=100 ^
    -c shared_buffers=8GB ^
    -c effective_cache_size=24GB ^
    -c maintenance_work_mem=2GB ^
    -c checkpoint_completion_target=0.9 ^
    -c wal_buffers=16MB ^
    -c default_statistics_target=500 ^
    -c random_page_cost=1.1 ^
    -c effective_io_concurrency=200 ^
    -c work_mem=36157kB ^
    -c huge_pages=try ^
    -c min_wal_size=4GB ^
    -c max_wal_size=16GB ^
    -c max_worker_processes=16 ^
    -c max_parallel_workers_per_gather=8 ^
    -c max_parallel_workers=16 ^
    -c max_parallel_maintenance_workers=4 ^
    -c max_locks_per_transaction=1024