3.6. 3D City Database using Docker¶
The 3DCityDB Docker images are available for PostgreSQL/PostGIS and Oracle.
The PostgreSQL/PostGIS version is based on the official
PostgreSQL and
PostGIS Docker images.
The Oracle version is based on the
Oracle Database Enterprise Edition images available from the
Oracle Container registry.
The images described here are available for 3DCityDB version v4.1.0
and newer.
Images for older 3DCityDB versions are available from
TUM-GIS 3DCityDB Docker images.
When designing the images we tried to stay as close as possible to the behavior of the base images and the 3DCityDB Shell scripts. Thus, all configuration options you may be used to from the base images are available for the 3DCityDB Docker images as well.
Synopsis
docker run --name 3dciytdb -port 5432:5432 -d \
-e POSTGRES_PASSDWORD=<theSecretPassword> \
-e SRID=<EPSG code> \
[-e HEIGHT_EPSG=<EPSG code>] \
[-e GMLSRSNAME=<mySrsName>] \
[-e POSTGRES_DB=<database name>] \
[-e POSTGRES_USER=<username>] \
[-e POSTGIS_SFCGAL=<true|false|yes|no>] \
3dcitydb/3dcitydb-pg
docker run --name 3dciytdb -port 5432:5432 -d \
-e ORACLE_USER=<theUserName> \
-e ORACLE_PASSDWORD=<theSecretPassword> \
-e SRID=<EPSG code> \
[-e HEIGHT_EPSG=<EPSG code>] \
[-e GMLSRSNAME=<mySrsName>] \
[-e ORACLE_PDB=<pluggable database name>] \
[-e DBVERSION=<oracle license option>] \
[-e VERSIONING=<version-enabled>] \
3dcitydb/3dcitydb-oracle
3.6.1. Image variants and versions¶
The images are available in various variants and versions. The PostgreSQL/PostGIS images are available based on Debian and Alpine Linux, the Oracles image are based on Oracle Linux. Table 3.28 gives an overview on the available image versions.
Tag | PostGIS (Debian) | PostGIS (Alpine) | Oracle |
---|---|---|---|
edge | |||
latest | |||
4.1.0 |
The edge images are automatically built and published on every push to the
master branch of the 3DCityDB Github repository
using the latest stable version of the base images.
The latest and release (e.g. 4.1.0
) image versions are only built
when a new release is published on Github. The latest tag will point to
the most recent release version using the latest base image version, e.g.
latest = 13-3.1-4.1.0
.
3.6.1.1. PostgreSQL/PostGIS images¶
The PostgreSQL/PostGIS images are available from 3DCityDB DockerHub and can be pulled like this:
docker pull 3dcitydb/3dcitydb-pg:TAG
The image tags are compose of the base image version, the
3DCityDB version and the image variant,
<base image version>-<3DCityDB version>-<image variant>
.
The base image version is inherited
from the PostGIS Docker images.
Debian is the default image variant, where no image variant is appended to the
tag. For the Alpine Linux images -alpine
is appended. Currently supported
base image versions are listed in Table 3.29.
PostgreSQL/PostGIS version | 2.5 | 3.0 | 3.1 |
---|---|---|---|
9.5 | 9.5-2.5 | 9.5-3.0 | |
9.6 | 9.6-2.5 | 9.6-3.0 | 9.6-3.1 |
10 | 10-2.5 | 10-3.0 | 10-3.1 |
11 | 11-2.5 | 11-3.0 | 11-3.1 |
12 | 12-2.5 | 12-3.0 | 12-3.1 |
13 | 13-3.0 | 13-3.1 |
The full list of available tags can be found on DockerHub Here are some examples for full image tags:
docker pull 3dcitydb/3dcitydb-pg:9.5-2.5-v4.1.0
docker pull 3dcitydb/3dcitydb-pg:13-3.1-v4.1.0
docker pull 3dcitydb/3dcitydb-pg:13-3.1-v4.1.0-alpine
docker pull 3dcitydb/3dcitydb-pg:13-3.1-v4.1.0-alpine
3.6.1.2. Oracle images¶
Due to Oracle licensing conditions we cannot offer Oracle images in a public repository like DockerHub at the moment. However, you can easily build the images yourself. A detailed description of how to do that is available in Section 3.6.3.2.
3.6.2. Usage and configuration¶
A 3DCityDB container is configured by settings environment variables inside
the container. For instance, this can be done using the -e VARIABLE=VALUE
flag of docker run. The 3DCityDB Docker images introduce the variables
SRID
, HEIGHT_EPSG
and GMLSRSNAME
. Their behavior
is described here.
Furthermore, some variables inherited from the base images offer important
configuration options, they are described separately for the
PostgreSQL/PostGIS and
Oracle image variants.
Tip
All variables besides POSTGRES_PASSWORD
and
ORACLE_PWD
are optional.
-
SRID
=<EPSG code>
¶ EPSG code for the 3DCityDB instance. If
SRID
is not set, the 3DCityDB schema will not be setup in the default database and you will end up with a plain PostgreSQL/PostGIS or Oracle container.
-
HEIGHT_EPSG
=<EPSG code>
¶ EPSG code of the height system, omit or use 0 if unknown or
SRID
is already 3D. This variable is used only for the automatic generation ofGMLSRSNAME
.
-
GMLSRSNAME
=<mySrsName>
¶ If set, the automatically generated
GMLSRSNAME
fromSRID
andHEIGHT_EPSG
is overwritten. If not set, the variable will be created automatically like this:If only
SRID
is set:GMLSRSNAME
=urn:ogc:def:crs:EPSG::SRID
If
SRID
andHEIGHT_EPSG
are set:GMLSRSNAME
=urn:ogc:def:crs,crs:EPSG::SRID,crs:EPSG::HEIGHT_EPSG
3.6.2.1. PostgreSQL/PostGIS environment variables¶
The 3DCityDB PostgreSQL/PostGIS Docker images make use of the following environment variables inherited from the official PostgreSQL and PostGIS Docker images. Refer to the documentations of both images for much more configuration options.
-
POSTGRES_DB
=<database name>
¶ Sets name for the default database. If not set, the default database is named like
POSTGRES_USER
.
-
POSTGRES_USER
=<username>
¶ Sets name for the database user, defaults to
postgres
.
-
POSTGRES_PASSWORD
=<password>
¶ Sets the password for the database connection. This variable is mandatory.
-
POSTGIS_SFCGAL
=<true|false|yes|no>
¶ If set, PostGIS SFCGAL support is enabled. Note: SFCGAL is currently only available in the Debian image variant. Setting the variable on Alpine images will have no effect.
3.6.2.2. Oracle environment variables¶
-
DBUSER
=<username>
¶ The database user name of the 3DCityDB instance to be created. The default value is ‘citydb’.
-
ORACLE_PWD
=<password>
¶ The database password of the 3DCityDB instance to be created. This variable is mandatory.
-
ORACLE_PDB
=<pluggable database name>
¶ set the name of the pluggable database (PDB) that should be used (default: ‘ORCLPDB1’). Requires Oracle 12c or higher.
-
DBVERSION
=<oracle license option>
¶ ‘S’ (default value) or ‘L’ to choose the Oracle Spatial or Locator license option for the 3DCityDB instance to be created.
-
VERSIONING
=<version-enabled>
¶ ‘yes’ or ‘no’ (default value) to specify whether the 3DCityDB instance should be versioned-enabled based on the Oracle’s Workspace Manager.
3.6.3. How to build images¶
This section describes how to build 3DCityDB Docker images on your own. Both the PostgreSQL/PostGIS and Oracle version offer one build argument, that can be used to set the tag of the base image that is used.
-
BASEIMAGE_TAG
=<tag of the base image>
¶ Tag of the base image that is used for the build. Available tags can be found on DockerHub for the PostgreSQL/PostGIS images and in the Oracle container registry.
3.6.3.1. PostgreSQL/PostGIS¶
The PostgreSQL/PostGIS images are build by cloning the 3DCityDB Github repository and running docker build:
Clone 3DCityDB Github repository and navigate to the
postgresql
folder in the repo:git clone https://github.com/3dcitydb/3dcitydb.git cd 3dcitydb/postgresql/
2. Build the Postgresql/PostGIS image using docker build:
docker build -t 3dcitydb/3dcitydb-pg . # or with a specific base image tag docker build -t 3dcitydb/3dcitydb-oracle \ --build-arg BASEIMAGE_TAG=13-3.1 \ .
3.6.3.2. Oracle¶
To build Oracle 3DCityDB Docker images, you need to create an Oracle account and accept the licensing conditions first:
Visit https://login.oracle.com/mysso/signon.jsp and create an account.
Visit https://container-registry.oracle.com and navigate to Database. Click the Continue button in the right column of the enterprise repository. Scroll to the bottom of the license agreement, which should be displayed now and click accept.
The repository listing should now show a green hook for the enterprise repository, as shown in the example below.
If this is the case, you are ready to pull the required base images from Oracle container registry.
Signin Docker to the Oracle container registry using the account credentials from above using docker login:
docker login container-registry.oracle.com
Clone the 3DCityDB repository and navigate to the
oracle
folder in the repo:
git clone https://github.com/3dcitydb/3dcitydb.git cd 3dcitydb/oracle/
Build the 3DCityDB Oracle image using docker build:
docker build -t 3dcitydb/3dcitydb-oracle . # or with a specific base image tag docker build . \ -t 3dcitydb/3dcitydb-oracle \ --build-arg BASEIMAGE_TAG=19.3.0.0
After the build process has finished, you are ready to use the image (see Section 3.6.2 and Section 3.6.2.2) or push it to a private Docker repository.