Docker Support

The vcdb-tool is also available as a Docker image, providing the full capabilities of the vcdb-tool command-line interface (CLI) for use in containerized applications and workflows. Using Docker is the fastest way to get started with vcdb-tool, as it requires no setup or installed Java runtime.

TL;DR

Linux
Windows CMD

docker run --rm --name vcdb-tool [-i -t] \
  [-e CITYDB_HOST=the.host.de] \
  [-e CITYDB_PORT=5432] \
  [-e CITYDB_NAME=theDBName] \
  [-e CITYDB_SCHEMA=theCityDBSchemaName] \
  [-e CITYDB_USERNAME=theUsername] \
  [-e CITYDB_PASSWORD=theSecretPass] \
  [-v /my/data/:/data] \
vcdb-tool[:TAG] COMMAND

docker run --rm --name vcdb-tool [-i -t] ^
  [-e CITYDB_HOST=the.host.de] ^
  [-e CITYDB_PORT=5432] ^
  [-e CITYDB_NAME=theDBName] ^
  [-e CITYDB_SCHEMA=theCityDBSchemaName] ^
  [-e CITYDB_USERNAME=theUsername] ^
  [-e CITYDB_PASSWORD=theSecretPass] ^
  [-v "C:\my\data:/data" ] ^
vcdb-tool[:TAG] COMMAND

Use the help command to list all CLI options and arguments. For subcommands (e.g. import citygml) us the syntax import help citygml to display detailed help for that specific subcommand.

Get the vcdb-tool Docker image

Using a pre-built image

Pre-built Docker images for each vcdb-tool 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, use the following command to load the image into your local Docker Engine:

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

By default, the Docker image is registered under the name vcdb-tool:<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-tool 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, RUNTIME_IMAGE_TAG, which allows you to specify the Eclipse Temurin base image to use for the vcdb-tool Docker image. The Eclipse Temurin project provides ready-to-use Docker images for Java Runtime Environments based on OpenJDK. A full list of available tags can be found on Docker Hub. If RUNTIME_IMAGE_TAG is not provided, a default base image will be used.

To build the vcdb-tool Docker image, run the following command.

Linux
Windows CMD

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

# Build using a specific Eclipse Temurin base image tag
docker build . -t vcdb-tool \
    --build-arg RUNTIME_IMAGE_TAG=<TAG>

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

# Build using a specific Eclipse Temurin base image tag
docker build . -t vcdb-tool ^
    --build-arg RUNTIME_IMAGE_TAG=<TAG>

Ensure to replace <TAG> with the desired version of the Eclipse Temurin base image, such as 21-jre-noble.

Usage and configuration

The vcdb-tool Docker image requires no configuration for most use cases and allows using the vcdb-tool CLI out of the box. Simply append the vcdb-tool COMMAND you want to execute to the docker run command line. A full list of available commands is documented here.

Show help and CLI documentation

Use the help command to see the CLI documentation and list all available commands:

docker run -i -t --rm [...] vcdb-tool[:TAG] help

Run help COMMAND to see the CLI documentation for a specific command:

docker run -i -t --rm [...] vcdb-tool[:TAG] help import
docker run -i -t --rm [...] vcdb-tool[:TAG] help export
docker run -i -t --rm [...] vcdb-tool[:TAG] help delete
# ...

If the command has subcommands, use help SUBCOMMAND to get a description of the subcommand:

docker run -i -t --rm [...] vcdb-tool[:TAG] import help citygml

Mounts for data exchange

Most vcdb-tool operations such as imports and exports require a mounted directory to exchange data between the host system and the container. You can use the -v or --mount options with the docker run command to mount a directory or file. The default working directory inside the container is /data.

Linux
Windows CMD

# mount /my/data/ on the host system to /data
docker run -i -t --rm --name vcdb-tool \
  -v /my/data/:/data \
vcdb-tool[:TAG] COMMAND

# mount C:\my\data on the host system to /data
docker run -i -t --rm --name vcdb-tool ^
  -v "C:\my\data:/data" ^
vcdb-tool[:TAG] COMMAND

When working with mounts, ensure that all directories and file paths passed to the vcdb-tool CLI are specified from the container’s perspective. If you’re not familiar with Docker volumes or bind mounts, refer to the Docker volume guide for guidance.

Interactive console

To allocate an interactive console session for the container, use the -i and -t options together with docker run. This is especially useful if you prefer to enter the VCDB password interactively instead of passing it on the command line. In such cases, use the -p option of vcdb-tool without a value, as shown in the example below.

Linux
Windows CMD

docker run -i -t --rm --name vcdb-tool \
  -v /my/data/:/data \
vcdb-tool[:TAG] import citygml \
  -H my.host.de -d citydb -u postgres -p -- \
  mycity.gml

docker run -i -t --rm --name vcdb-tool ^
  -v "C:\my\data:/data" ^
vcdb-tool[:TAG] import citygml ^
  -H my.host.de -d citydb -u postgres -p -- ^
  mycity.gml

Environment variables

The recommended way to provide database connection details to the vcdb-tool container is by setting them as environment variables. The following environment variables are supported by vcdb-tool:

Environment variable Description

Environment variable	Description
`CITYDB_HOST`	Name of the host on which the VCDB is running.
`CITYDB_PORT`	Port of the VCDB server.
`CITYDB_NAME`	Name of the VCDB database to connect to.
`CITYDB_SCHEMA`	Schema to use when connecting to the VCDB.
`CITYDB_USER`	Username to use when connecting to the VCDB.
`CITYDB_PASSWORD`	Password to use when connecting to the VCDB.
`CITYDB_CONN_PROPS`	Database-specific connection properties provided as comma-separated list of `property=value` pairs.

CITYDB_HOST

Name of the host on which the VCDB is running.

CITYDB_PORT

Port of the VCDB server.

CITYDB_NAME

Name of the VCDB database to connect to.

CITYDB_SCHEMA

Schema to use when connecting to the VCDB.

CITYDB_USER

Username to use when connecting to the VCDB.

CITYDB_PASSWORD

Password to use when connecting to the VCDB.

CITYDB_CONN_PROPS

Database-specific connection properties provided as comma-separated list of property=value pairs.

Environment variables can be used alongside command-line options and configuration files. However, they have the lowest precedence and are overridden by these options. More information about the use of environment variables with vcdb-tool is available here.

User management and file permissions

When exchanging files between the host system and the vcdb-tool container, it is important to ensure that file and directory permissions are set correctly. For security reasons (see Docker best practices), the vcdb-tool runs as a non-root user by default inside the container. The default user is ubuntu, with a user and group ID (UID, GID) of 1000.

Linux
Windows CMD

docker run --rm --entrypoint bash vcdb-tool[:TAG] \
  -c "cat /etc/passwd | grep $(whoami)"
# ubuntu:x:1000:1000:Ubuntu:/home/ubuntu:/bin/bash

docker run --rm --entrypoint bash vcdb-tool[:TAG] ^
  -c "cat /etc/passwd | grep $(whoami)"
# ubuntu:x:1000:1000:Ubuntu:/home/ubuntu:/bin/bash

Since 1000 is the default UID/GID for the first user on many Linux distributions, you typically will not encounter permission issues because the host user will usually match the container user. However, if you do run into file permission problems, you can run the vcdb-tool container as a different user using the -u option with the docker run command. This ensures that generated files in the mounted directory have the correct ownership and permissions.

The following example illustrates how to use the -u option to pass the user and group ID of your current host’s user on Linux and UNIX-like machines.

docker run --rm --name vcdb-tool \
  -u $(id -u):$(id -g) \
  -v /my/data/:/data \
vcdb-tool[:TAG] COMMAND

Examples

The following examples assume that a VCDB v5 instance is set up and running, using the connection details shown below:

VCDB hostname:   my.host.de
VCDB port:       5432
VCDB name:       citydb
VCDB username:   postgres
VCDB password:   changeMe

Importing CityGML

This section provides examples of how to import CityGML datasets. For a detailed explanation of the vcdb-tool import command, see here.

To import the CityGML dataset /my/data/mycity.gml from your host system into the VCDB instance given above, use the following command:

Linux
Windows CMD

docker run --rm --name vcdb-tool \
  -v /my/data/:/data \
vcdb-tool[:TAG] import citygml \
  -H my.host.de -d citydb -u postgres -p changeMe \
  mycity.gml

docker run --rm --name vcdb-tool ^
  -v "C:\my\data:/data" ^
vcdb-tool[:TAG] import citygml ^
  -H my.host.de -d citydb -u postgres -p changeMe ^
  mycity.gml

Since the host directory /my/data/ is mounted to the default working directory /data inside the container, you can simply reference your input file by its filename instead of using an absolute path.

The following command imports all CityGML datasets from /my/data/ on your host system into the VCDB instance:

Linux
Windows CMD

docker run --rm --name vcdb-tool \
  -v /my/data/:/data \
vcdb-tool[:TAG] import citygml \
  -H my.host.de -d citydb -u postgres -p changeMe \
  /data/

docker run --rm --name vcdb-tool ^
  -v "C:\my\data:/data" ^
vcdb-tool[:TAG] import citygml ^
  -H my.host.de -d citydb -u postgres -p changeMe ^
  /data/

Exporting CityGML

To export all data stored in the given VCDB instance to a single CityGML file /my/data/output.gml, use the command below. For a detailed explanation of the vcdb-tool export command, see here.

Linux
Windows CMD

docker run --rm --name vcdb-tool \
  -v /my/data/:/data \
vcdb-tool[:TAG] export citygml \
  -H my.host.de -d citydb -u postgres -p changeMe \
  -o output.gml

docker run --rm --name vcdb-tool ^
  -v "C:\my\data:/data" ^
vcdb-tool[:TAG] export citygml ^
  -H my.host.de -d citydb -u postgres -p changeMe ^
  -o output.gml

Combining VCDB and vcdb-tool containers

This example demonstrates how to use the VCDB and vcdb-tool Docker images together. It walks through the process of creating and setting up a VCDB container, importing a CityGML test dataset, and then exporting the data in both CityGML and CityJSON formats.

The example uses the CityGML 2.0 dataset railway_scene_lod3_v2.zip, which comes bundled with vcdb-tool and is located in the samples/datasets subfolder of the installation directory. This dataset uses the coordinate reference system (CRS) EPSG:25833. You may also use any other CityGML dataset of your choice.

Preparing the Docker network

The first step is to create a Docker network named vcdb-net. All containers used in this example will be attached to this network via the --network option of docker run. This setup allows you to use container names as hostnames, enabling seamless communication between vcdb-tool and the VCDB database container.

docker network create vcdb-net

Docker provides many networking options for connecting containers. For more details, refer to the Docker networking overview.

Setting up the VCDB container

Now let’s create a VCDB instance using the VCDB Docker image. We name the container vcdb (line 3), attach it to the network created above (line 4), and use the SRID of our test dataset (lines 6-7).

Linux
Windows CMD

docker run -t -d --name vcdb \
  --network vcdb-net \
  -e POSTGRES_PASSWORD=changeMe \
  -e SRID=25833 \
  -e SRS_NAME="urn:ogc:def:crs,crs:EPSG::25833,crs:EPSG::5783" \
vcdb-pg[:TAG]

docker run -t -d --name vcdb ^
  --network vcdb-net ^
  -e POSTGRES_PASSWORD=changeMe ^
  -e SRID=25833 ^
  -e SRS_NAME="urn:ogc:def:crs,crs:EPSG::25833,crs:EPSG::5783" ^
vcdb-pg[:TAG]

After successfully running the command above, the VCDB container will be available with the following properties:

SRID:            25833
SRS name:        urn:ogc:def:crs,crs:EPSG::25833,crs:EPSG::5783
VCDB name:       postgres
VCDB schema:     citydb
VCDB username:   postgres
VCDB password:   changeMe

To verify this, you can check the console log of the VCDB database container:

docker logs vcdb

Importing the test dataset

Next, import the test dataset railway_scene_lod3_v2.zip into the VCDB using the vcdb-tool Docker image. To make the dataset accessible inside the container, mount the directory containing the file to the /data path using the -v or --mount option as described above.

Linux
Windows CMD

docker run -i -t --rm --name vcdb-tool \
  --network vcdb-net \
  -v /my/data/:/data \
vcdb-tool[:TAG] import citygml \
  -H vcdb \
  -d postgres \
  -u postgres \
  -p changeMe \
  railway_scene_lod3_v2.zip

docker run -i -t --rm --name vcdb-tool ^
  --network vcdb-net ^
  -v "C:\my\data:/data" ^
vcdb-tool[:TAG] import citygml ^
  -H vcdb ^
  -d postgres ^
  -u postgres ^
  -p changeMe ^
  railway_scene_lod3_v2.zip

Exporting the test data as CityGML

After successfully importing the test dataset into the VCDB container, you can now export the data as CityGML 3.0 again. As with the import command, ensure that the target directory on your host system is mounted into the container. On Linux, it is also recommended to run the vcdb-tool container using the same UID/GID as the host user to avoid permission issues with the exported files.

Linux
Windows CMD

docker run -i -t --rm --name vcdb-tool \
  -u "$(id -u):$(id -g)" \
  --network vcdb-net \
  -v /my/data/:/data \
vcdb-tool[:TAG] export citygml \
  -H vcdb \
  -d postgres \
  -u postgres \
  -p changeMe \
  -o output.gml

docker run -i -t --rm --name vcdb-tool ^
  --network vcdb-net ^
  -v "C:\my\data:/data"" ^
vcdb-tool[:TAG] export citygml ^
  -H vcdb ^
  -d postgres ^
  -u postgres ^
  -p changeMe ^
  -o output.gml

Exporting the test data as CityJSON

If you prefer the output in CityJSON format, simply use the export cityjson command and adjust the output filename accordingly.

Linux
Windows CMD

docker run -i -t --rm --name vcdb-tool \
  -u "$(id -u):$(id -g)" \
  --network vcdb-net \
  -v /my/data/:/data \
vcdb-tool[:TAG] export cityjson \
  -H vcdb \
  -d postgres \
  -u postgres \
  -p changeMe \
  -o output.json

docker run -i -t --rm --name vcdb-tool ^
  --network vcdb-net ^
  -v "C:\my\data:/data"" ^
vcdb-tool[:TAG] export cityjson ^
  -H vcdb ^
  -d postgres ^
  -u postgres ^
  -p changeMe ^
  -o output.json

Cleaning up

If you no longer need the VCDB, you can remove its container, data volume, and network using the following commands.

docker rm -f -v vcdb
docker network rm vcdb-net