Docker-Unterstützung

Die VCDB ist auch als Docker-Image verfügbar, das auf den offiziellen Docker-Images von PostgreSQL und PostGIS aufbaut. Es ist so konzipiert, dass es das Verhalten der Basis-Images sowie der Shell-Skripte der VCDB möglichst genau widerspiegelt. Daher werden alle Konfigurationsoptionen, die in den Basis-Images verfügbar sind, auch vom VCDB Docker-Image unterstützt.

Die VCDB Docker-Images ab Version 5.0 sind ausschließlich für PostgreSQL/PostGIS verfügbar und nur kompatibel mit den vcdb-tool Docker-Images. Weitere Informationen zur Kompatibilität mit VC Suite Produkten und CityGML-Versionen finden Sie hier.

TL;DR

  • Linux

  • Windows CMD

docker run --name vcdb -p 5432:5432 -d \
    -e POSTGRES_PASSWORD=<theSecretPassword> \
    -e SRID=<EPSG code> \
    [-e HEIGHT_EPSG=<EPSG code>] \
    [-e SRS_NAME=<mySrsName>] \
    [-e POSTGRES_DB=<database name>] \
    [-e POSTGRES_USER=<username>] \
    [-e POSTGIS_SFCGAL=<true|false|yes|no>] \
vcdb-pg[:TAG]
docker run --name vcdb -p 5432:5432 -d ^
    -e POSTGRES_PASSWORD=<theSecretPassword> ^
    -e SRID=<EPSG code> ^
    [-e HEIGHT_EPSG=<EPSG code>] ^
    [-e SRS_NAME=<mySrsName>] ^
    [-e POSTGRES_DB=<database name>] ^
    [-e POSTGRES_USER=<username>] ^
    [-e POSTGIS_SFCGAL=<true|false|yes|no>] ^
vcdb-pg[:TAG]

VCDB Docker-Images erhalten

Vorgefertigtes Image verwenden

Vorgefertigte Docker-Images für jede VCDB-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-postgres-docker-image-<version>.tar.gz

Standardmäßig wird das Docker-Image unter dem Namen vcdb-pg:<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-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 BASEIMAGE_TAG, mit dem Sie das PostgreSQL/PostGIS Basis-Image angeben können, das für das Erstellen des VCDB Docker-Images verwendet werden soll. Eine vollständige Übersicht verfügbarer Tags finden Sie auf Docker Hub. Wird BASEIMAGE_TAG nicht angegeben, wird ein Standard-Basis-Image verwendet.

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

  • Linux

  • Windows CMD

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

# Mit einem spezifischen TAG des PostgreSQL/PostGIS Basis-Images erstellen
docker build . -t vcdb-pg \
    --build-arg BASEIMAGE_TAG=<TAG>
# Mit einem Standard-Basis-Image erstellen
docker build -t vcdb-pg .

# Mit einem spezifischen TAG des PostgreSQL/PostGIS Basis-Images erstellen
docker build . -t vcdb-pg ^
    --build-arg BASEIMAGE_TAG=<TAG>
Ersetzen Sie <TAG> durch die gewünschte Version des PostgreSQL/PostGIS Basis-Images, wie z.B. 17-3.5.

Verwendung und Konfiguration

Ein VCDB-Container wird durch das Setzen von Umgebungsvariablen innerhalb des Containers konfiguriert. Dies kann über die Option -e VARIABLE=VALUE des docker run Befehls erfolgen.

Das VCDB Docker-Image definiert die Umgebungsvariablen SRID, HEIGHT_EPSG, SRS_NAME und CHANGELOG zur Konfiguration der VCDB-Instanz. Weitere Umgebungsvariablen, die vom Basis-Image geerbt werden, bieten zusätzliche Optionen zur Konfiguration der zugrunde liegenden PostgreSQL/PostGIS Datenbank.

Die folgende Tabelle listet die am häufigsten verwendeten Umgebungsvariablen zur Einrichtung eines VCDB-Containers auf.

Umgebungsvariable Beschreibung

SRID

Gibt die Spatial Reference ID des Koordinatenreferenzsystems (CRS) an, das für die VCDB-Instanz verwendet wird. Wird SRID nicht angegeben, wird die VCDB-Instanz nicht erstellt, und der Container startet als normale PostgreSQL/PostGIS Instanz.

HEIGHT_EPSG

EPSG-Code des Höhenbezugssystems. Dieser Wert kann weglassen oder auf 0 (Standard) gesetzt werden, wenn das Höhenbezugssystem unbekannt ist oder die angegebene SRID bereits ein 3D-Referenzsystem definiert.

SRS_NAME

Der OGC-konforme Name des CRS. Dieser Name wird zum Beispiel beim Export von Daten in die CityGML/CityJSON-Dateien geschrieben. Wird SRS_NAME nicht gesetzt, wird ein Name aus den SRID und HEIGHT_EPSG Werten abgeleitet.

CHANGELOG

Auf yes setzen, um die Changelog-Erweiterung für die VCDB-Instanz zu aktivieren. Standard ist no.

POSTGRES_USER

Benutzername für die VCDB-Datenbank. Standard ist postgres.

POSTGRES_DB

Name der VCDB-Datenbank. Wird POSTGRES_DB nicht gesetzt, wird standardmäßig der Wert von POSTGRES_USER verwendet.

POSTGRES_PASSWORD

Passwort für die VCDB-Datenbank. Diese Variable ist obligatorisch.

POSTGIS_SFCGAL

Auf true setzen, um die PostGIS-Erweiterung postgis_sfcgal zu aktivieren, oder false (Standard), um sie zu deaktivieren.

PROJ_NETWORK

Aktiviert das Herunterladen von Gitter-Dateien für die Koordinatentransformation. Aufgrund von Änderungen in aktuellen PostGIS Basis-Images sollte diese Variable auf on gesetzt werden, wenn Koordinatentransformationen in der VCDB durchgeführt werden sollen.
Alle Variablen bis auf POSTGRES_PASSWORD und SRID sind optional.

Performance-Tuning

Die Konfiguration der PostgreSQL-Datenbank innerhalb des VCDB-Containers kann die Performance erheblich beeinflussen, insbesondere bei Import- und Export-Operationen. PostgreSQL bietet verschiedene Konfigurationsparameter, die die Leistung verbessern und Funktionen wie Query-Parallelisierung aktivieren können.

Während die Datenbankoptimierung grundsätzlich ein komplexes Thema ist, können Tools wie PGTune dabei helfen, empfohlene Konfigurationseinstellungen für Ihr System einfach und schnell zu erzeugen, um die Performance zu verbessern.

  1. Öffnen Sie die PGTune Website und füllen Sie das Formular mit Ihren Systemparametern aus. PGTune erzeugt daraufhin empfohlene Einstellungen wie die folgenden:

    # DB Version: 13
# OS Type: linux
# DB Type: mixed
# Total Memory (RAM): 8 GB
# CPUs num: 8
# Connections num: 20
# Data Storage: ssd

max_connections = 20
shared_buffers = 2GB
effective_cache_size = 6GB
maintenance_work_mem = 512MB
checkpoint_completion_target = 0.9
wal_buffers = 16MB
default_statistics_target = 100
random_page_cost = 1.1
effective_io_concurrency = 200
work_mem = 13107kB
min_wal_size = 1GB
max_wal_size = 4GB
max_worker_processes = 8
max_parallel_workers_per_gather = 4
max_parallel_workers = 8
max_parallel_maintenance_workers = 4

  2. Um die Einstellungen anzuwenden, übergeben Sie sie an den postgres Befehl mit der -c Option beim Starten Ihres VCDB-Containers mit docker run (siehe Zeilen 4ff.).

    • Linux

    • Windows CMD

    docker run -d -i -t --name vcdb -p 5432:5342 \
    -e SRID=25832 \
    -e POSTGRES_PASSWORD=changeMe \
    vcdb-pg[:TAG] postgres \
    -c max_connections=20 \
    -c shared_buffers=2GB \
    -c effective_cache_size=6GB \
    -c maintenance_work_mem=512MB \
    -c checkpoint_completion_target=0.9 \
    -c wal_buffers=16MB \
    -c default_statistics_target=100 \
    -c random_page_cost=1.1 \
    -c effective_io_concurrency=200 \
    -c work_mem=13107kB \
    -c min_wal_size=1GB \
    -c max_wal_size=4GB \
    -c max_worker_processes=8 \
    -c max_parallel_workers_per_gather=4 \
    -c max_parallel_workers=8 \
    -c max_parallel_maintenance_workers=4
    docker run -d -i -t --name vcdb -p 5432:5342 ^
    -e SRID=25832 ^
    -e POSTGRES_PASSWORD=changeMe ^
    vcdb-pg[:TAG] postgres ^
    -c max_connections=20 ^
    -c shared_buffers=2GB ^
    -c effective_cache_size=6GB ^
    -c maintenance_work_mem=512MB ^
    -c checkpoint_completion_target=0.9 ^
    -c wal_buffers=16MB ^
    -c default_statistics_target=100 ^
    -c random_page_cost=1.1 ^
    -c effective_io_concurrency=200 ^
    -c work_mem=13107kB ^
    -c min_wal_size=1GB ^
    -c max_wal_size=4GB ^
    -c max_worker_processes=8 ^
    -c max_parallel_workers_per_gather=4 ^
    -c max_parallel_workers=8 ^
    -c max_parallel_maintenance_workers=4

Hinweise für hoch-parallelisierte Systeme

Wenn Sie den VCDB Docker-Container auf einem Server mit vielen CPU-Kernen ausführen, kann eine geeignete Feinabstimmung eine hohe Query-Parallelisierung ermöglichen. Hochgradig parallele Abfragen können jedoch auch dazu führen, dass PostgreSQL den verfügbaren Shared Memory überschreitet.

Um dies zu verhindern, wird empfohlen, die Shared-Memory-Zuweisung von Docker über die --shm-size Option des docker run Befehls zu erhöhen. Stellen Sie außerdem sicher, dass die PostgreSQL-Einstellung shared_buffers entsprechend erhöht wird. Tests zeigen auch, dass da Anpassen des Parameters max_locks_per_transaction wichtig ist, um insbesondere unter hoher Last deutliche Performance-Verbesserungen zu erzielen.

Nachfolgend sind beispielhafte Systemparameter und Konfigurationseinstellungen dargestellt, die mit PGTune erzeugt wurden.

# DB Version: 17
# OS Type: linux
# DB Type: dw
# Total Memory (RAM): 32 GB
# CPUs num: 16
# Connections num: 100
# Data Storage: ssd

max_connections = 100
shared_buffers = 8GB
effective_cache_size = 24GB
maintenance_work_mem = 2GB
checkpoint_completion_target = 0.9
wal_buffers = 16MB
default_statistics_target = 500
random_page_cost = 1.1
effective_io_concurrency = 200
work_mem = 36157kB
huge_pages = try
min_wal_size = 4GB
max_wal_size = 16GB
max_worker_processes = 16
max_parallel_workers_per_gather = 8
max_parallel_workers = 16
max_parallel_maintenance_workers = 4

Eine entsprechende Konfiguration des VCDB Docker-Containers mit --shm-size, shared_buffers und max_locks_per_transaction könnte dann wie folgt aussehen:

  • Linux

  • Windows CMD

docker run -d -i -t --name vcdb -p 5432:5342 \
    --shm-size=8g \
    -e SRID=25832 \
    -e POSTGRES_PASSWORD=changeMe \
    vcdb-pg[:TAG] postgres \
    -c max_connections=100 \
    -c shared_buffers=8GB \
    -c effective_cache_size=24GB \
    -c maintenance_work_mem=2GB \
    -c checkpoint_completion_target=0.9 \
    -c wal_buffers=16MB \
    -c default_statistics_target=500 \
    -c random_page_cost=1.1 \
    -c effective_io_concurrency=200 \
    -c work_mem=36157kB \
    -c huge_pages=try \
    -c min_wal_size=4GB \
    -c max_wal_size=16GB \
    -c max_worker_processes=16 \
    -c max_parallel_workers_per_gather=8 \
    -c max_parallel_workers=16 \
    -c max_parallel_maintenance_workers=4 \
    -c max_locks_per_transaction=1024
docker run -d -i -t --name vcdb -p 5432:5342 ^
    --shm-size=8g ^
    -e SRID=25832 ^
    -e POSTGRES_PASSWORD=changeMe ^
    vcdb-pg[:TAG] postgres ^
    -c max_connections=100 ^
    -c shared_buffers=8GB ^
    -c effective_cache_size=24GB ^
    -c maintenance_work_mem=2GB ^
    -c checkpoint_completion_target=0.9 ^
    -c wal_buffers=16MB ^
    -c default_statistics_target=500 ^
    -c random_page_cost=1.1 ^
    -c effective_io_concurrency=200 ^
    -c work_mem=36157kB ^
    -c huge_pages=try ^
    -c min_wal_size=4GB ^
    -c max_wal_size=16GB ^
    -c max_worker_processes=16 ^
    -c max_parallel_workers_per_gather=8 ^
    -c max_parallel_workers=16 ^
    -c max_parallel_maintenance_workers=4 ^
    -c max_locks_per_transaction=1024