Installation
In this chapter we will describe how to install the geoDB infrastructure. The infrastructure consists of four main components:
A Python client/API accessing the database through the PostGrest RestAPI (this version)
A PosGIS database (Version 14)
A geoDB extension to be installed into the PostGIS database (this version)
A PostGrest RestAPI (Version 7)
1. Installing the geoDB Client/API
The aim of the chapter is to describe the installation of the geoDB client which serves as a wrapper to accessing an existing geoDB service. You can omit steps 2.-4. entirely if you have gained access to such a service (e.g. by buying geoDB access through the eurodatacube service).
Installation Using the Package Manager conda/mamba
The xcube geodb client is preferably installed into a conda environment. Ensure that you use Python 3 (>=3.6). The geoDB client has not been tested with Python 2 and will very likely not work.
You install the client using conda
$ conda install -c conda-forge xcube_geodb
$ conda activate xcube_geodb
The client comes with a jupyter lab pre-installed. To launch the lab type:
$ conda activate xcube_geodb
$ jupyter lab
We have described the installation using the standard package managerconda
.
However, we strongly encourage you to consider using mamba
instead,
particularly if you combine the geoDB with xcube.
Installation from Sources
We discourage you to install from source. However, if you are a developer, use the following steps.
Clone the repository using git
:
$ git clone https://github.com/dcs4cop/xcube-geodb.git
$ cd xcube-geodb
You need to create the conda environment to install all dependencies:
$ conda env create
Once the environment has been created you can activate the environment and install the geoDB client:
$ conda activate xcube-geodb
$ python setup.py develop
2. Installation of the Database Backend
This section describes how to set up the geoDB PostGIS database. The geoDB PostGIS database consists of three software components:
A PostGreSQl database (version 14)
A PostGIS extension (version 14)
The geoDB extension (this version)
The easiest way is to use docker. We maintain a docker image that includes all these three components hosted on quay.io.
docker run -p 5432:5432 -e POSTGRES_PASSWORD=mypassword quay.io/bcdev/xcube-geodb-backend
For more information about the docker image refer to the PostGIS docker image.
Another option is to install the geoDB extension into an existing PostGIS instance. Prerequisite is, though, that you have full access to your database. If so, you can use a Makefile in our geoDB client repository. To do so clone the repository and move into the sql directory of the xcube_geodb package:
$ git clone https://github.com/dcs4cop/xcube-geodb.git
$ cd xcube-geodb/xcube_geodb/sql
You will find a Makefile
in this directory. Before you can install the geodb extension you need to ensure that
the xcube geodb version is set properly in the filename of the SQL file.
export GEODB_VERSION=<version>
make release_version
After the execution of the above make command, you will find two new files in your directory:
geodb.control
andgeodb--<version>.sql
It is essential that those exist and that the version in the SQL file name matches the geoDB software version you attempt to install. The extension will not install otherwise.
Once the above-mentioned files exist, run make install
. This will install all necessary files into your PostGIS
directory structure.
Lastly, open a PostGreSQL console or a database GUI of your choice as super-user and enter the following SQL command:
CREATE EXTENSION geodb;
3. Installation of the Postgrest RestAPI
One of the main objectives of the geoDB is to offer an easy way for users to gain access to a PostGIS database
via a RestAPI. The geoDB takes advantage of the existing PostGreSQL restAPI Postgrest
version 7.0.1 (we aim to upgrade to version 9 as it integrates better with PostGIS in the future).
To configure a postgrest instance please refer to the postgrest configuration docs. We will give an example in the next chapter where we talk about authorization and authentication.
5. Installation of the geoserver
The geoDB Python client provides a wrapper around publishing geoDB collections as an e.g. WMS service to a Geoserver instance. In order to access such a server, the geoDB client needs access to a Geoserver instance using the credentials of a generic Geoserver user. The current geoDB setup uses the docker image of the Geoserver version 2.19.1 (image: terrestris/geoserver:2.19.1).
When installing this docker image we ran into CORS issues and a wrong redirect to a http not https URL after login. The redirect and CORS issues have been resolved by the following settings in the Kubernetes setup:
geoserver:
geoserverCsrfWhitelist: xcube-geodb.brockmann-consult.de
proxyBaseUrl: https://xcube-geodb.brockmann-consult.de/geoserver
These values are imputed as environment variables into the Geoserver container and should also be configurable
in the web.xml
in /usr/local/tomcat/webapps/geoserver/WEB-INF
.
In addition, a vectortile plugin has been added to the geoserver image by building a custom docker image
hosted on quay.io (current version: quay.io/bcdev/xcube-geoserv:1.0.3
) build using this
Dockerfile.
For any more detailed information about installation, please refer to this Dockerfile or the original Installation instructions.
Please be aware that the admin credentials should be changed after installation. Otherwise, any user with even the most mediocre intelligence will be able to log on as admin.