Docker-Unterstützung

Das vcdb-tool ist auch als Docker-Image verfügbar und bietet alle Funktionen der Kommandozeilen-Schnittstelle (CLI) von vcdb-tool für den Einsatz in containerisierten Anwendungen und Workflows. Die Verwendung von Docker ist der schnellste Weg, um mit vcdb-tool zu starten, da keine Einrichtung oder Installation einer Java-Laufzeitumgebung erforderlich ist.

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
Der help Befehl listet alle CLI-Optionen und Argumente auf. Für Unterbefehle (z.B. import citygml) verwenden Sie die Syntax import help citygml, um die detaillierte Hilfe für den entsprechenden Unterbefehl anzuzeigen.

vcdb-tool Docker-Image erhalten

Verwendung eines vorgefertigten Images

Vorgefertigte Docker-Images für jede vcdb-tool Version sind als ZIP-Pakete über unsere Software-Downloadseite erhältlich. Jedes Paket enthält die Image-Datei im .tar.gz Format und eine Schnellstartanleitung, die bei den ersten Schritten hilft. Nach dem Entpacken des Pakets laden Sie das Image mit folgendem Befehl in Ihre lokale Docker Engine:

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

Standardmäßig wird das Docker-Image unter dem Namen vcdb-tool:<version> registriert, wobei die Release-Version (<version>) als Image-Tag verwendet wird.

Eigenes Image erstellen

Wenn Sie das Docker-Image lieber selbst erstellen möchten, laden Sie zunächst das ZIP-Paket mit der vcdb-tool Software von unserer Software-Downloadseite herunter. Nach dem Entpacken finden Sie im Stammverzeichnis eine Datei namens Dockerfile. Sie können diese Datei unverändert verwenden oder an Ihre spezifischen Anforderungen anpassen.

Das Dockerfile unterstützt das optionale Build-Argument RUNTIME_IMAGE_TAG, mit dem Sie das Eclipse Temurin Basis-Image angeben können, das für das Erstellen des vcdb-tool Docker-Images verwendet werden soll. Das Eclipse Temurin Projekt stellt einsatzbereite Docker-Images für Java Runtime Environments basierend auf OpenJDK bereit. Eine vollständige Übersicht verfügbarer Tags finden Sie auf Docker Hub. Wird RUNTIME_IMAGE_TAG nicht angegeben, wird ein Standard-Basis-Image verwendet.

Um das vcdb-tool Docker-Image zu erstellen, führen Sie den folgenden Befehl aus.

  • Linux

  • Windows CMD

# Mit einem Standard-Basis-Image erstellen
docker build -t vcdb-tool .

# Mit einem spezifischen TAG des Eclipse Temurin Basis-Images erstellen
docker build . -t vcdb-tool \
    --build-arg RUNTIME_IMAGE_TAG=<TAG>
# Mit einem Standard-Basis-Image erstellen
docker build -t vcdb-tool .

# Mit einem spezifischen TAG des Eclipse Temurin Basis-Images erstellen
docker build . -t vcdb-tool ^
    --build-arg RUNTIME_IMAGE_TAG=<TAG>
Ersetzen Sie <TAG> durch die gewünschte Version des Eclipse Temurin Basis-Images, wie z.B. 21-jre-noble.

Verwendung und Konfiguration

Das vcdb-tool Docker-Image benötigt in den meisten Fällen keine Konfiguration und ermöglicht die direkte Verwendung der vcdb-tool CLI. Hängen Sie einfach den vcdb-tool Befehl an die docker run Befehlszeile an. Eine vollständige Liste der verfügbaren Befehle ist hier dokumentiert.

Hilfe und CLI-Dokumentation anzeigen

Der help Befehl gibt die CLI-Dokumentation aus und listet alle verfügbaren Befehle auf:

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

help COMMAND gibt die CLI-Dokumentation für einen bestimmten Befehl aus:

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
# ...

Falls der Befehl Unterbefehle hat, kann help SUBCOMMAND für die Beschreibung des Unterbefehls verwendet werden:

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

Mounts für den Datenaustausch

Die meisten vcdb-tool Operationen wie Importe und Exporte erfordern ein gemountetes Verzeichnis, um Daten zwischen dem Host-System und dem Container auszutauschen. Die Optionenen -v oder --mount können mit dem docker run Befehl verwendet werden, um ein Verzeichnis oder eine Datei einzubinden. Das standardmäßige Arbeitsverzeichnis innerhalb des Containers ist /data.

  • Linux

  • Windows CMD

# Mount von /my/data/ auf dem Host-System nach /data
docker run -i -t --rm --name vcdb-tool \
  -v /my/data/:/data \
vcdb-tool[:TAG] COMMAND
# Mount von C:\my\data auf dem Host-System nach /data
docker run -i -t --rm --name vcdb-tool ^
  -v "C:\my\data:/data" ^
vcdb-tool[:TAG] COMMAND
Bei der Arbeit mit Mounts muss darauf geachtet werden, dass alle Verzeichnisse und Dateipfade, die an die vcdb-tool CLI übergeben werden, aus der Perspektive des Containers angegeben werden. Für weitere Informationen zur Verwendung von Docker-Volumes oder Bind-Mounts lesen Sie bitte den Docker Volume Leitfaden.

Interaktive Konsole

Um eine interaktive Konsolensitzung für den Container zu öffnen, verwenden Sie die Optionen -i und -t zusammen mit docker run. Dies ist besonders nützlich, wenn das VCDB-Passwort interaktiv eingegeben werden soll, anstatt es in der Kommandozeile anzugeben. Verwenden Sie für diesen Fall die Option -p von vcdb-tool ohne Wert, wie im folgenden Beispiel gezeigt.

  • 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

Umgebungsvariablen

Der empfohlene Weg, Verbindungsparameter für die VCDB-Instanz an den vcdb-tool Container zu übergebenm, ist das Setzen von Umgebungsvariablen. Die folgenden Umgebungsvariablen werden von vcdb-tool unterstützt:

Umgebungsvariable Beschreibung

CITYDB_HOST

Hostname des VCDB Datenbankservers.

CITYDB_PORT

Port des VCDB Datenbankservers.

CITYDB_NAME

Name der VCDB-Instanz, zu eine Verbindung hergestellt werden soll.

CITYDB_SCHEMA

Schema, das beim Verbinden zur VCDB verwendet werden soll.

CITYDB_USER

Benutzername für die Verbidung zur VCDB.

CITYDB_PASSWORD

Passwort für die Verbindung zur VCDB.

CITYDB_CONN_PROPS

Datenbankspezifische Verbindungsparameter als kommaseparierte Liste von property=value Paaren.
Umgebungsvariablen können zusammen mit Kommandozeilenoptionen und Konfigurationsdateien verwendet werden. Sie haben jedoch die niedrigste Priorität und werden von diesen Alternativen überschrieben. Weitere Informationen zur Verwendung von Umgebungsvariablen mit vcdb-tool finden Sie hier.

Benutzerverwaltung und Dateiberechtigungen

Beim Austausch von Dateien zwischen dem Host-System und dem vcdb-tool Container ist es wichtig, dass Datei- und Verzeichnisberechtigungen korrekt gesetzt sind. Aus Sicherheitsgründen (siehe Docker Best Practices) läuft das vcdb-tool standardmäßig als Non-Root Benutzer innerhalb des Containers. Der Standardbenutzer ist ubuntu mit einer Benutzer- und Gruppen-ID (UID, GID) von 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

Da 1000 die Standard-UID/GID für den ersten Benutzer auf vielen Linux-Distributionen ist, treten in der Regel keine Berechtigungsprobleme auf, da der Host-Benutzer meist mit dem Container-Benutzer übereinstimmt. Sollten dennoch Probleme mit Dateiberechtigungen auftreten, kann der vcdb-tool Container mit einem anderen Benutzer ausgeführt werden, indem die Option -u des docker run Befehls verwendet wird. Dies stellt sicher, dass erzeugte Dateien im gemounteten Verzeichnis den richtigen Eigentümer und korrekte Dateiberechtigungen haben.

Das folgende Beispiel zeigt, wie Sie die Option -u verwenden, um die Benutzer- und Gruppen-ID Ihres aktuellen Host-Benutzers unter Linux- und UNIX-ähnlichen Systemen zu übergeben.

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

Beispiele

Die nachfolgenden Beispiele setzen voraus, dass eine VCDB v5 Instanz eingerichtet und in Betrieb ist. Für eine Verbindung mit dieser Instanz werden die unten angegebenen Verbdinungsparameter angenommen:

VCDB-Hostname:       my.host.de
VCDB-Port:           5432
VCDB-Name:           citydb
VCDB-Benutzername:   postgres
VCDB-Passwort:       changeMe

Import von CityGML-Dateien

Dieser Abschnitt beinhaltet Beispiele für den Import von CityGML-Dateien. Eine ausführliche Dokumentation des vcdb-tool import Befehls finden Sie hier.

Um die CityGML-Datei /my/data/mycity.gml vom Host-System in die oben angegebene VCDB-Instanz zu importieren, kann der folgende Befehl verwendet werden:

  • 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
Da das Host-Verzeichnis /my/data/ auf das standardmäßige Arbeitsverzeichnis /data innerhalb des Containers gemountet ist, kann die Eingabedatei auch einfach über den Dateinamen anstelle eines absoluten Pfads angegeben werden.

Der folgende Befehl importiert alle CityGML-Dateien im Verzeichnis /my/data/ auf dem Host-System in die VCDB-Instanz:

  • 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/

Export von CityGML-Dateien

Um alle in der angegebenen VCDB-Instanz gespeicherten Daten in eine einzelne CityGML-Datei /my/data/output.gml zu exportieren, kann der unten stehende Befehl verwendet werden. Eine ausführliche Dokumentation des vcdb-tool export Befehls finden Sie hier.

  • 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

Kombination von VCDB und vcdb-tool Containern

Dieses Beispiel zeigt, wie die Docker-Images der VCDB und von vcdb-tool gemeinsam verwendet werden können. Es führt durch den Prozess der Erstellung und Einrichtung eines VCDB-Containers, des Import eines CityGML-Testdatensatzes und anschließend des Export der Daten im CityGML- und CityJSON-Formaten.

Im Beispiel wird der CityGML 2.0 Datensatz railway_scene_lod3_v2.zip verwendet, der mit vcdb-tool ausgeliefert wird. Er befindet sich im Unterordner samples/datasets des Installationsverzeichnisses. Dieser Datensatz verwendet das Koordinatenreferenzsystem (CRS) EPSG:25833. Sie können aber auch jeden anderen CityGML-Datensatz Ihrer Wahl verwenden.

Vorbereitung des Docker-Netzwerks

Der erste Schritt besteht darin, ein Docker-Netzwerk mit dem Namen vcdb-net zu erstellen. Alle in diesem Beispiel verwendeten Container werden über die Option --network von docker run mit diesem Netzwerk verbunden. Durch dieses Setup können Container-Namen als Hostnamen verwendet werden, was eine direkte Kommunikation zwischen vcdb-tool und dem VCDB-Datenbankcontainer ermöglicht.

docker network create vcdb-net
Docker bietet viele Netzwerkoptionen zur Verbindung von Containern. Weitere Informationen finden Sie in der Docker Netzwerk-Übersicht.

Einrichten des VCDB-Containers

Nun kann eine VCDB-Instanz mithilfe des VCDB Docker-Images erstellt werden. Der Container erhält den Namen vcdb (Zeile 3), wird mit dem zuvor erstellten Netzwerk verbunden (Zeile 4) und verwendet die SRID des Testdatensatzes als Datenbank-CRS (Zeilen 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]

Nach dem erfolgreichen Ausführen des obigen Befehls ist der VCDB-Container mit den folgenden Eigenschaften einsatzbereit:

SRID:                25833
SRS-Name:            urn:ogc:def:crs,crs:EPSG::25833,crs:EPSG::5783
VCDB-Name:           postgres
VCDB-Schema:         citydb
VCDB-Benutzername:   postgres
VCDB-Passwort:       changeMe

Um dies zu überprüfen, kann das Konsolenprotkoll des VCDB-Cntainers abgerufen werden:

docker logs vcdb

Import des Testdatensatzes

Als nächstes wird der Testdatensatz railway_scene_lod3_v2.zip mit dem vcdb-tool Docker-Image in die VCDB importiert. Um den Datensatz im Containers verfügbar zu machen, wird das Verzeichnis, das die Datei enthält, über die Option -v oder --mount auf den Pfad /data eingehängt, wie oben beschrieben.

  • 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

Export der Testdaten als CityGML

Nachdem der Testdatensatzes erfolgreich in den VCDB-Container importiert wurde, können die Daten als CityGML 3.0 exportiert werden. Wie beim import Befehl muss auch hier sichergestellt werden, dass das Zielverzeichnis auf dem Host-System im Container eingebunden ist. Unter Linux wird außerdem empfohlen, den vcdb-tool Container mit derselben UID/GID wie der Host-Benutzer auszuführen, um Berechtigungsprobleme mit den exportierten Dateien zu vermeiden.

  • 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

Export der Testdaten als CityJSON

Wird eine Ausgabe im CityJSON-Format bevorzugt, muss einfach der Befehl export cityjson verwendet werden und der Name der Ausgabedatei entsprechend angepasst werden.

  • 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

Aufräumen

Wenn die VCDB nicht mehr benötigt wird, können der VCDB-Container, das Daten-Volume und das Netzwerk mit den folgenden Befehlen aufgeräumt werden.

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