citydb-tool Docker

The citydb-tool Docker images expose the capabilities of the citydb-tool CLI for dockerized applications and workflows. Using Docker is the quickest way to get started with citydb-tool, as no setup and installed Java runtime are required. See here for more on how to get Docker.

Docker image compatibility

3DCityDB v5 introduces a substantially changed database schema, that requires a new set of tools.

Currently, only citydb-tool is compatible with 3DCityDB v5.

Usage of 3DCityDB v4 tools (3DCityDB Importer/Exporter, 3D Web Map Client, 3DCityDB Web Feature Service (WFS)) is still possible by migrating data to a 3DCityDB v4. See here for more details on compatibility of CityGML versions and citydb-tools, and how to migrate data between versions.

TL;DR

LinuxWindows CMD

docker run --rm --name citydb-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] \
3dcitydb/citydb-tool[:TAG] COMMAND

docker run --rm --name citydb-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:\users\me\mydata:/data" ] ^
3dcitydb/citydb-tool[:TAG] COMMAND

Tip

Use the help command to list all CLI parameters and arguments. For subcommands (e.g. import citygml) us this syntax import help citygml to show CLI options.

Image versions

The citydb-tool Docker images are based on Eclpise Temurin JRE 21. They are available from 3DCityDB DockerHub or Github Container registry (ghcr.io).

Dockerhubghcr.io

docker pull 3dcitydb/citydb-tool

docker pull ghcr.io/3dcitydb/citydb-tool

Tags

We publish images for two types of events. For each release on Github (e.g. v1.2.3) we provide a set of images using the citydb-tool version as tag. The tags composed of <major>.<minor> and <major> are volatile and point to the latest citydb-tool release. For instance, the images tagged 1 or 1.2 will point to 1.2.3, if this is the latest version. This is useful if you want automatic updates for minor or micro releases. The latest tag points alway to the latest release version.

Dockerhubghcr.io

docker pull 3dcitydb/citydb-tool:1.0.0
docker pull 3dcitydb/citydb-tool:1.0
docker pull 3dcitydb/citydb-tool:1
docker pull 3dcitydb/citydb-tool:latest

docker pull ghcr.io/3dcitydb/citydb-tool:1.0.0
docker pull ghcr.io/3dcitydb/citydb-tool:1.0
docker pull ghcr.io/3dcitydb/citydb-tool:1
docker pull ghcr.io/3dcitydb/citydb-tool:latest

For each push to the main branch of the citydb-tool repository we publish a fresh version of the edge image tag.

Warning

The edge image contains the latest state of development. It may contain bugs and should not be used for production purposes. Only use this image if you have a specific reason, e.g. testing an unreleased feature.

Dockerhubghcr.io

docker pull 3dcitydb/citydb-tool:edge

docker pull ghcr.io/3dcitydb/citydb-tool:edge

Version overview

Following table gives an overview on the available image versions and sizes.

Tag	Build status	Size
edge
latest
1.0.0

Note

Minor releases are not listed in this table.

The latest citydb-tool version is:

The latest image version on DockerHub is:

Usage and configuration

The citydb-tool Docker images do not require configuration for most use cases and allow the usage of the citydb-tool CLI out of the box. Simply append the citydb-tool command you want to execute to the docker run command line. The commands of citydb-tool are documented here.

docker run -i -t --rm --name citydb-tool 3dcitydb/citydb-tool COMMAND

Help and CLI documentation

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

docker run -i -t --rm 3dcitydb/citydb-tool help

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

docker run -i -t --rm 3dcitydb/citydb-tool help import
docker run -i -t --rm 3dcitydb/citydb-tool help export
docker run -i -t --rm 3dcitydb/citydb-tool help delete
# ...

To see the usage description of a subcommand, use the help function of the top level command:

docker run -i -t --rm 3dcitydb/citydb-tool import help citygml

Mounts for data import and export

All import and export operations require a mounted directory for exchanging data between the host system and the container. Use the -v or --mount options of the docker run command to mount a directory or file. The default working directory inside the container is /data.

Mount a folderMount current working directory

LinuxWindows CMD

# mount /my/data/ on the host system to /data
docker run -i -t --rm --name citydb-tool \
  -v /my/data/:/data \
3dcitydb/citydb-tool COMMAND

# mount /my/data/ on the host system to /data
docker run -i -t --rm --name citydb-tool ^
  -v "c:\users\me\mydata:/data" ^
3dcitydb/citydb-tool COMMAND

LinuxWindows CMD

# Mount the current working directory on the host system to /data
docker run -i -t --rm --name citydb-tool \
  -v $PWD:/data \
3dcitydb/citydb-tool COMMAND

# Mount the current working directory on the host system to /data
docker run -i -t --rm --name citydb-tool ^
  -v "%cd%:/data" ^
3dcitydb/citydb-tool COMMAND

Tip

Watch out for correct paths when working with mounts! All paths passed to the citydb-tool CLI have to be specified from the container's perspective. If you are not familiar with Docker volumes and bind mounts go through the Docker volume guide.

In order to allocate an interactive console session for the container process, you must use the docker run options -i and -t together. This comes in handy, for instance, if you don't want to pass the password for the 3DCityDB connection on the command line but rather want to be prompted to enter it interactively on the console. You must use the -p option of the citydb-tool CLI without a value for this purpose as shown in the example below.

LinuxWindows CMD

docker run -i -t --rm --name citydb-tool \
  -v /my/data/:/data \
3dcitydb/citydb-tool import \
  -H my.host.de -d citydb -u postgres -p \
  bigcity.gml

docker run -i -t --rm --name citydb-tool ^
  -v "c:\users\me\mydata:/data" ^
3dcitydb/citydb-tool import ^
  -H my.host.de -d citydb -u postgres -p ^
  bigcity.gml

The docker run command offers further options to configure the container process. Please check the official reference for more information.

Environment variables

The citydb-tool Docker images support the following environment variables to set the credentials for the connection to a 3DCityDB instance. A detailed documentation of the environment variables is available here.

Warning

When running the citydb-tool on the command line, the values of these variables will be used as input if a corresponding CLI option is not available. The CLI options always take precedence over the environmental variables.

CITYDB_HOST=hostname or ip

Name of the host or IP address on which the 3DCityDB is running.

CITYDB_PORT=port

Port of the 3DCityDB to connect to. Default is 5432, the default PostgreSQL port.

CITYDB_NAME=DB name

Name of the 3DCityDB database to connect to. Default is postgres.

CITYDB_SCHEMA=citydb

Schema to use when connecting to the 3DCityDB (default: citydb or username).

CITYDB_USERNAME=username

Username to use when connecting to the 3DCityDB.

CITYDB_PASSWORD=thePassword

Password to use when connecting to the 3DCityDB.

User management and file permissions

When exchanging files between the host system and the citydb-tool container, it is import to make sure that files and directories have permissions set correctly. For security reasons (see here) the citydb-tool runs as non-root user by default inside the container. The default user is named impexp with user and group identifier (uid, gid) = 1000.

LinuxWindows CMD

docker run --rm --entrypoint bash 3dcitydb/citydb-tool \
  -c "cat /etc/passwd | grep ubuntu"
# ubuntu:x:1000:1000:Ubuntu:/home/ubuntu:/bin/bash

docker run --rm --entrypoint bash 3dcitydb/citydb-tool ^
  -c "cat /etc/passwd | grep ubuntu"
# ubuntu:x:1000:1000:Ubuntu:/home/ubuntu:/bin/bash

As 1000 is the default uid/gid for the first user on many Linux distributions in most cases you won't notice this, as the user on the host system is going to have the same uid/gid as inside the container. However, if you are facing file permission issues, you can run the citydb-tool container as another user with the -u option of the docker run command. This way you can make sure, that the right permissions are set on generated files in the mounted directory.

The following example illustrates how to use the -u option to pass the user ID of your current host's user.

LinuxWindows CMD

docker run --rm --name citydb-tool \
  -u $(id -u):$(id -g) \
  -v /my/data/:/data \
3dcitydb/citydb-tool COMMAND

docker run --rm --name citydb-tool ^
  -u $(id -u):$(id -g) ^
  -v "c:\users\me\mydata:/data" ^
3dcitydb/citydb-tool COMMAND

Build your own images

3DCityDB citydb-tool images are easy to build on your own. The image supports two build arguments:

BUILDER_IMAGE_TAG='21-jdk-noble'

Tag off the image to use for the build stage. This is usually not required to set. All available Eclipse Temurin image tags can be found here.

RUNTIME_IMAGE_TAG='21-jre-noble'

Tag off the image to use for the runtime stage. This is usually not required to set. It can be used to set a specific base image version. All available Eclipse Temurin image tags can be found here.

Build process

1. Clone the citydb-tool Github repository and navigate to the cloned repo:

   git clone https://github.com/3dcitydb/citydb-tool.git
   cd citydb-tool
   

2. Checkout the release version, branch, or commit you want to build form. Available release tags, branches, and commits can be found on Github.

   git checkout [TAG|BRANCH|COMMIT]
   

3. Build the image using docker build:

   docker build -t 3dcitydb/citydb-tool .
   

Examples

For the following examples we assume that a 3DCityDB instance with the following settings is running:

DB HOSTNAME   my.host.de
DB PORT       5432
DB NAME       citydb
DB USERNAME   postgres
DB PASSWORD   changeMe

Importing CityGML

This section provides some examples for importing CityGML datasets. Refer to import for a detailed description of the citydb-tool CLI import command.

Import the CityGML dataset /home/me/mydata/bigcity.gml on you host system into the DB given above:

LinuxWindows CMD

docker run --rm --name citydb-tool \
  -v /home/me/mydata/:/data \
3dcitydb/citydb-tool import citygml \
  -H my.host.de -d citydb -u postgres -p changeMe \
  bigcity.gml

docker run --rm --name citydb-tool ^
  -v "c:\users\me\mydata:/data" ^
3dcitydb/citydb-tool import citygml ^
  -H my.host.de -d citydb -u postgres -p changeMe ^
  bigcity.gml

Note

Since the host directory /home/me/mydata/ 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.

Import all CityGML datasets from /home/me/mydata/ on your host system into the DB given above:

LinuxWindows CMD

docker run --rm --name citydb-tool \
  -v /home/me/mydata/:/data \
3dcitydb/citydb-tool import citygml \
  -H my.host.de -d citydb -u postgres -p changeMe \
  /data/

docker run --rm --name citydb-tool ^
  -v "c:\users\me\mydata:/data" ^
3dcitydb/citydb-tool import citygml ^
  -H my.host.de -d citydb -u postgres -p changeMe ^
  /data/

Exporting CityGML

This section provides some examples for exporting CityGML datasets. Refer to export for a detailed description of the citydb-tool CLI export command.

Export all data from the DB given above to /home/me/mydata/output.gml:

LinuxWindows CMD

docker run --rm --name citydb-tool \
  -v /home/me/mydata/:/data \
3dcitydb/citydb-tool export \
  -H my.host.de -d citydb -u postgres -p changeMe \
  -o output.gml

docker run --rm --name citydb-tool ^
  -v "c:\users\me\mydata:/data" ^
3dcitydb/citydb-tool export ^
  -H my.host.de -d citydb -u postgres -p changeMe ^
  -o output.gml

citydb-tool Docker combined with 3DCityDB Docker

This example shows how to use the 3DCityDB and citydb-tool Docker images in conjunction. We will download a CityGML 2.0 test dataset, create a 3DCityDB, import the test data, and create a CityGML 3.0 and CityJSON export.

Data preparation

Let's begin by downloading a test dataset: Railway Scene LoD3 dataset

For this example we assume the downloaded data is at your current working directory. We use the well known $PWD environment variable to specify all paths in the following, e.g. $PWD/Railway_Scene_LoD3.zip. Below are some examples for common Linux tools to download the file, but you can use the URL above too.

wgetcurl

wget "https://github.com/3dcitydb/importer-exporter/raw/master/resources/samples/Railway%20Scene/Railway_Scene_LoD3.zip"

curl -LO "https://github.com/3dcitydb/importer-exporter/raw/master/resources/samples/Railway%20Scene/Railway_Scene_LoD3.zip"

The test dataset uses following coordinate reference system:

SRID        3068
SRS_NAME    urn:ogc:def:crs,crs:EPSG::3068,crs:EPSG::5783

You can read this information from the unpacked CityGML .gml files srsName property or extract it with a text search utility like grep.

grep -i -m 1 srsName Railway_Scene_LoD3_exp.gml

Networking preparation

The next step is to bring up a Docker network called citydb-net. We will attach all containers in this example to this network using the --network option of docker run. This will allow us to use container names as hostnames for connecting citydb-tool to the database.

# docker network remove citydb-net

docker network create citydb-net

Tip

There are many other networking options to connect Docker containers. Take a look at the Docker networking overview to learn more.

3DCityDB creation

Now let's create a a 3DCityDB instance using the 3DCityDB Docker images. We name the container citydb (line 3), attach it to the network created above (line 4), and use the SRID and SRS_NAME of our test dataset (line 6-7).

LinuxWindows CMD

# docker rm -f -v citydb

docker run -t -d --name citydb \
  --network citydb-net \
  -e POSTGRES_PASSWORD=changeMe \
  -e SRID=3068 \
  -e SRS_NAME="urn:ogc:def:crs,crs:EPSG::3068,crs:EPSG::5783" \
3dcitydb/3dcitydb-pg

# docker rm -f -v citydb

docker run -t -d --name citydb ^
  --network citydb-net ^
  -e POSTGRES_PASSWORD=changeMe ^
  -e SRID=3068 ^
  -e SRS_NAME="urn:ogc:def:crs,crs:EPSG::3068,crs:EPSG::5783" ^
3dcitydb/3dcitydb-pg

We now have a 3DCityDB instance running with these properties:

3DCityDB Version    5.0.0
SRID                3068
SRS_NAME            urn:ogc:def:crs,crs:EPSG::3068,crs:EPSG::5783
DBNAME              postgres
SCHEMA NAME         citydb
DBUSER              postgres
DBPASSWORD          changeMe

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

docker logs citydb

Import data

The next step is to import our data to the 3DCityDB. Therefore, we need to mount our working directory ($PWD) containing the downloaded .zip file to the container, as shown in line 3. The emphasized line shows how to use the container name from the first step as hostname when both containers are attached to the same Docker network.

LinuxWindows CMD

docker run -i -t --rm --name citydb-tool \
  --network citydb-net \
  -v "$PWD:/data" \
3dcitydb/citydb-tool:edge import citygml \
  -H citydb \
  -d postgres \
  -u postgres \
  -p changeMe \
  "Railway_Scene_LoD3.zip"

docker run -i -t --rm --name citydb-tool ^
  --network citydb-net ^
  -v "%cd%:/data" ^
3dcitydb/citydb-tool:edge import citygml ^
  -H citydb ^
  -d postgres ^
  -u postgres ^
  -p changeMe ^
  "Railway_Scene_LoD3.zip"

Export CityGML v3.0

Now, with our data inside the 3DCityDB, let's use the citydb-tool to create a CityGML 3.0 export of the entire dataset. As CityGML 3.0 is the default export option, there are no additional options required for the export command. Same as for the import step above, we mount our current working directory for data exchange with the container. Additionally, we add the -o option to specify an output file name Railway_Scene_LoD3_CityGML_v3.gml (line 10) and set the container to run as the current user and group to make sure we have sufficient permissions for writing the output file (line 2, see here for more on permissions).

LinuxWindows CMD

docker run -i -t --rm --name citydb-tool \
  -u "$(id -u):$(id -g)" \
  --network citydb-net \
  -v "$PWD:/data" \
3dcitydb/citydb-tool:edge export citygml \
  -H citydb \
  -d postgres \
  -u postgres \
  -p changeMe \
  -o "Railway_Scene_LoD3_CityGML_v3.gml"

docker run -i -t --rm --name citydb-tool ^
  -u "$(id -u):$(id -g)" ^
  --network citydb-net ^
  -v "%cd%:/data" ^
3dcitydb/citydb-tool:edge export citygml ^
  -H citydb ^
  -d postgres ^
  -u postgres ^
  -p changeMe ^
  -o "Railway_Scene_LoD3_CityGML_v3.gml"

Export CityJSON

Creating a CityJSON export works the same way as described above for CityGML. The only differences are the changed citydb-tool command and export file name, as shown in the highlighted lines.

LinuxWindows CMD

docker run -i -t --rm --name citydb-tool \
  -u "$(id -u):$(id -g)" \
  --network citydb-net \
  -v "$PWD:/data" \
3dcitydb/citydb-tool:edge export cityjson \
  -H citydb \
  -d postgres \
  -u postgres \
  -p changeMe \
  -o "Railway_Scene_LoD3_CityJSON.json"

docker run -i -t --rm --name citydb-tool ^
  -u "$(id -u):$(id -g)" ^
  --network citydb-net ^
  -v "%cd%:/data" ^
3dcitydb/citydb-tool:edge export cityjson ^
  -H citydb ^
  -d postgres ^
  -u postgres ^
  -p changeMe ^
  -o "Railway_Scene_LoD3_CityJSON.json"

Cleanup

If you no longer need the 3DCityDB, its container, data volume, and the network can be disposed.

docker rm -f -v citydb
docker network rm citydb-net