Docker

The quickest way to get up and running with 3DCityDB is using Docker! On this page you will find quick start examples for the 3DCityDB and tools using Docker . Follow the examples to create a database, import CityGML data, and create an export in minutes.

TL;DR

• 3D City Database

  LinuxWindows

  docker run -d -p 5432:5432 --name citydb \
    -e POSTGRES_PASSWORD=changeMe! \
    -e SRID=25832 \
  3dcitydb/3dcitydb-pg
  

  docker run -d -p 5432:5432 --name citydb ^
    -e POSTGRES_PASSWORD=changeMe! ^
    -e SRID=25832 ^
  3dcitydb/3dcitydb-pg
  

• CityDB tool

  LinuxWindows

  docker run -i -t --rm --name citydb-tool \
    -v /my/data/:/data \
    -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 \
  3dcitydb/3dcitydb-pg [help|import|export|delete|index]
  

  docker run -i -t --rm --name citydb-tool ^
    -v /my/data/:/data ^
    -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 ^
  3dcitydb/3dcitydb-pg [help|import|export|delete|index]
  

  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.

What is Docker?

Docker is a widely used virtualization technology that makes it possible to pack an application with all its required resources into a standardized unit - the Docker Container. Software encapsulated in this way can run on Linux, Windows, macOS and most cloud services without any further changes or setup process. Docker containers are lightweight compared to traditional virtualization environments that emulate an entire operating system, because they contain only the application and all the tools, program libraries, and files it requires.

Docker enables you to get a 3DCityDB instance up and running in a fews seconds, without having to setup a database server or the 3DCityDB database schema, as shown below.

Figure 1. Setup a 3DCityDB instance using Docker and establish a connection to the ready-to-use 3DCityDB in seconds.

Get Docker

To run the 3DCityDB images you need to install Docker Engine. Installation instructions for Linux are available here. For Windows it is recommended to download and install Docker Desktop.

Docker images overview

Docker images are available for the following tools of the 3DCityDB software suite:

• 3D City Database
• CityDB tool
• 3DCityDB Importer/Exporter
• 3D Web Map Client
• 3DCityDB Web Feature Service (WFS)

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 3DCityDB tools, and how to migrate data between versions.

Get 3DCityDB Docker images

All images are available from DockerHub or Github container registry (ghcr.io). An overview on available versions and image variants is available here.

• 3D City Database

  DockerHubGithub container registry

  docker pull 3dcitydb/3dcitydb-pg
  

  docker pull ghcr.io/3dcitydb/3dcitydb-pg
  

  Tip

  To benefit of the latest bugfixes and features of PostgreSQL/PostGIS spatial functions we recommend to use the alpine image versions. See here for more details on the differences between the debian and alpine image variants.

  DockerHubGithub container registry

  docker pull 3dcitydb/3dcitydb-pg:latest-alpine
  

  docker pull ghcr.io/3dcitydb/3dcitydb-pg:latest-alpine
  

• CityDB tool

  DockerHubGithub container registry

  docker pull 3dcitydb/citydb-tool
  

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

Quick start examples

The following sections provide quick start code snippets for all 3DCityDB Docker images to get you running in a few seconds. For a more comprehensive documentation please visit the individual chapters of each image.

• 3DCityDB Docker
• CityDB tool Docker

3DCityDB Docker

To run a PostgreSQL/PostGIS 3DCityDB container the only required settings are a database password (POSTGRES_PASSWORD) and the EPSG code of the coordinate reference system (SRID) of the 3DCityDB instance. Use the docker run -p switch to define a port to expose to the host system for database connections. The detailed documentation for the 3DCityDB Docker image is available here.

LinuxWindows

docker run -d -p 5432:5432 --name cdb \
  -e POSTGRES_PASSWORD=changeMe \
  -e SRID=25832 \
3dcitydb/3dcitydb-pg

docker run -d -p 5432:5432 --name cdb ^
  -e POSTGRES_PASSWORD=changeMe ^
  -e SRID=25832 ^
3dcitydb/3dcitydb-pg

A container started with the command above will host a 3DCityDB instance configured like this:

CONTAINER NAME    cdb
DB HOST           localhost or 127.0.0.1
DB PORT           5432
DB NAME           postgres
DB USER           postgres
DB PASSWD         changeMe
DB SRID           25832
DB GMLSRSNAME     urn:ogc:def:crs:EPSG::25832

CityDB tool Docker

The Docker image exposes the commands of the citydb-tool. The environment variables listed below allow to specify a 3DCityDB v5 connection. To exchange data for import or export with the container, mount a host folder to /data inside the container.

LinuxWindows

docker run --rm --name citydb-tool -i -t \
  -e CITYDB_HOST=the.host.de \
  -e CITYDB_NAME=theDBName \
  -e CITYDB_USERNAME=theUsername \
  -e CITYDB_PASSWORD=theSecretPass \
  -v /my/data/:/data \
3dcitydb/citydb-tool COMMAND # (1)!

1. The commands of citydb-tool are documented here.

docker run --rm --name citydb-tool -i -t ^
  -e CITYDB_HOST=the.host.de ^
  -e CITYDB_NAME=theDBName ^
  -e CITYDB_USERNAME=theUsername ^
  -e CITYDB_PASSWORD=theSecretPass ^
  -v /my/data/:/data ^
3dcitydb/citydb-tool COMMAND # (1)!

1. The commands of citydb-tool are documented here.

Show 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

Import CityGML data

Run the import command to import a CityGML dataset located at /local/data/dir/data.gml.

LinuxWindows

docker run -i -t --rm -u $(id -u):$(id -g) \
  --network host \
  -v ${PWD}:/data/ \
  -e CITYDB_HOST=localhost \
  -e CITYDB_NAME=postgres \
  -e CITYDB_USERNAME=postgres \
  -e CITYDB_PASSWORD=changeMe \
3dcitydb/citydb-tool import citygml "/data/*.gml"

docker run -i -t --rm -u $(id -u):$(id -g) ^
  --network host ^
  -v ${PWD}:/data/ ^
  -e CITYDB_HOST=localhost ^
  -e CITYDB_NAME=postgres ^
  -e CITYDB_USERNAME=postgres ^
  -e CITYDB_PASSWORD=changeMe ^
3dcitydb/citydb-tool import citygml "/data/*.gml"

Export CityGML data

Run the export command to export a CityGML dataset to /local/data/dir/export.gml.

LinuxWindows

docker run -i -t --rm -u $(id -u):$(id -g) \
  --network host \
  -v ${PWD}:/data/ \
  -e CITYDB_HOST=localhost \
  -e CITYDB_NAME=postgres \
  -e CITYDB_USERNAME=postgres \
  -e CITYDB_PASSWORD=changeMe \
3dcitydb/citydb-tool export citygml -o "/data/export.gml"

docker run -i -t --rm -u $(id -u):$(id -g) ^
  --network host ^
  -v ${PWD}:/data/ ^
  -e CITYDB_HOST=localhost ^
  -e CITYDB_NAME=postgres ^
  -e CITYDB_USERNAME=postgres ^
  -e CITYDB_PASSWORD=changeMe ^
3dcitydb/citydb-tool export citygml -o "/data/export.gml"

The exported file will be available on the host system at: /local/data/dir/export.gml.