Using Docker

The quickest way to get up and running with VCDB is using Docker image docker . On this page you will find quick start examples for the VCDB and vcdb-tool using Docker. Follow the examples to create a database, import CityGML data, and create an export in minutes.

A much more detailed example on importing and exporting data using VCDB and vcdb-tool with Docker can be found here.

TL;DR

VC Database: Create a VCDB Docker container with SRID=25832.

Linux
Windows CMD

docker run -d -p 5432:5432 --name vcdb \
  -e POSTGRES_PASSWORD=changeMe \
  -e SRID=25832 \
vcdb-pg[:TAG]

docker run -d -p 5432:5432 --name vcdb ^
  -e POSTGRES_PASSWORD=changeMe ^
  -e SRID=25832 ^
vcdb-pg[:TAG]

vcdb-tool: Connect to the container specified above.

Linux
Windows CMD

docker run -i -t --rm --name vcdb-tool \
  --network host \
  -v /my/data/:/data \
  -e CITYDB_HOST=localhost \
  -e CITYDB_PORT=5432 \
  -e CITYDB_NAME=postgres \
  -e CITYDB_USERNAME=postgres \
  -e CITYDB_PASSWORD=changeMe \
vcdb-tool[:TAG] [help|import|export|delete|index]

docker run -i -t --rm --name vcdb-tool ^
  --network host ^
  -v /my/data/:/data ^
  -e CITYDB_HOST=localhost ^
  -e CITYDB_PORT=5432 ^
  -e CITYDB_NAME=postgres ^
  -e CITYDB_USERNAME=postgres ^
  -e CITYDB_PASSWORD=changeMe ^
vcdb-tool[:TAG] [help|import|export|delete|index

What is Docker?

Docker image 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 VCDB instance up and running in a few seconds, without having to set up a database server or the VCDB database schema.

Get Docker

To run the VCDB Docker images, you must first install Docker Engine. Installation instructions for Linux are available here. For Windows users, we recommend downloading and installing Docker Desktop.

Get Docker images

Docker images for VCDB and vcdb-tool are available from our software download page. Each image is tagged by release version. Each download package includes instructions for loading the pre-built images into your Docker Engine. If you prefer to build images yourself, see the corresponding VCDB and vcdb-tool sections.

Quick start examples

The following sections provide quick start code snippets for all VCDB Docker images to get you running in a few seconds.

VCDB Docker

To run a PostgreSQL/PostGIS VCDB container, the only required settings are a database password (POSTGRES_PASSWORD) and the Spatial Reference ID (SRID) of the coordinate reference system to be used for the VCDB instance. Use the -p option of the docker run command to define a port to expose to the host system for database connections.

Linux
Windows CMD

docker run -d -p 5432:5432 --name vcdb \
  -e POSTGRES_PASSWORD=changeMe \
  -e SRID=25832 \
vcdb-pg[:TAG]

docker run -d -p 5432:5432 --name vcdb ^
  -e POSTGRES_PASSWORD=changeMe ^
  -e SRID=25832 ^
vcdb-pg[:TAG]

Ensure to replace TAG with the release version of the image, e.g. vcdb-pg:5.0.0.
The detailed documentation for the VCDB Docker image is available here.

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

Property	Value
Container name	vcdb
VCDB host	localhost or 127.0.0.1
VCDB port	5432
VCDB name	postgres
VCDB username	postgres
VCDB password	changeMe
VCDB SRID	25832
VCDB CRS name	urn:ogc:def:crs:EPSG::25832

Property

Value

Container name

vcdb

VCDB host

localhost or 127.0.0.1

VCDB port

5432

VCDB name

postgres

VCDB username

postgres

VCDB password

changeMe

VCDB SRID

25832

VCDB CRS name

urn:ogc:def:crs:EPSG::25832

vcdb-tool Docker

The vcdb-tool Docker image exposes the commands of the vcdb-tool command-line utility. The environment variables listed below allow specifying a VCDB v5 connection. To exchange data for import or export with the container, mount a host folder to /data inside the container.

Linux
Windows CMD

docker run --rm --name vcdb-tool -i -t \
  --network host \
  -e CITYDB_HOST=localhost \
  -e CITYDB_NAME=postgres \
  -e CITYDB_USERNAME=postgres \
  -e CITYDB_PASSWORD=changeMe \
  -v /my/data/:/data \
vcdb-tool[:TAG] COMMAND (1)

1	The commands of `vcdb-tool` are documented here.

docker run --rm --name vcdb-tool -i -t ^
  --network host ^
  -e CITYDB_HOST=localhost ^
  -e CITYDB_NAME=postgres ^
  -e CITYDB_USERNAME=postgres ^
  -e CITYDB_PASSWORD=changeMe ^
  -v "C:\mydata:/data" ^
vcdb-tool[:TAG] COMMAND (1)

1	The commands of `vcdb-tool` are documented here.

Ensure to replace TAG with the release version of the image, e.g. vcdb-tool:1.0.0.
The detailed documentation for the vcdb-tool Docker image is available here.

Show help and CLI documentation

Use the help command to see the documentation of the command-line interface (CLI) 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

Import CityGML data

Run the import command to import a CityGML dataset located at /local/data/dir/data.gml (Linux) or C:\local\data\dir\data.gml (Windows).

Linux
Windows CMD

docker run -i -t --rm -u $(id -u):$(id -g) \
  --network host \
  -v /local/data/dir:/data/ \
  -e CITYDB_HOST=localhost \
  -e CITYDB_NAME=postgres \
  -e CITYDB_USERNAME=postgres \
  -e CITYDB_PASSWORD=changeMe \
vcdb-tool[:TAG] import citygml "/data/data.gml"

docker run -i -t --rm ^
  --network host ^
  -v "C:\local\data\dir:/data/" ^
  -e CITYDB_HOST=localhost ^
  -e CITYDB_NAME=postgres ^
  -e CITYDB_USERNAME=postgres ^
  -e CITYDB_PASSWORD=changeMe ^
vcdb-tool[:TAG] import citygml "/data/data.gml"

Export CityGML data

Run the export command to export a CityGML dataset to /local/data/dir/export.gml (Linux) or C:\local\data\dir\export.gml (Windows).

Linux
Windows CMD

docker run -i -t --rm -u $(id -u):$(id -g) \
  --network host \
  -v /local/data/dir:/data/ \
  -e CITYDB_HOST=localhost \
  -e CITYDB_NAME=postgres \
  -e CITYDB_USERNAME=postgres \
  -e CITYDB_PASSWORD=changeMe \
vcdb-tool[:TAG] export citygml -o "/data/export.gml"

docker run -i -t --rm ^
  --network host ^
  -v "C:\local\data\dir:/data/" ^
  -e CITYDB_HOST=localhost ^
  -e CITYDB_NAME=postgres ^
  -e CITYDB_USERNAME=postgres ^
  -e CITYDB_PASSWORD=changeMe ^
vcdb-tool[:TAG] export citygml -o "/data/export.gml"

A much more detailed example on importing and exporting data using VCDB and vcdb-tool Docker can be found here.