|
| 1 | +# Installation |
| 2 | + |
| 3 | +In this chapter we describe 1) how to install the Python client, which is the |
| 4 | +user interface to the xcube geoDB, and 2) how to set up the xcube geoDB |
| 5 | +infrastructure. Steps 2.-4. are only relevant if you wish to install your own |
| 6 | +instance of xcube geoDB. The usual case is that you have acquired access to the |
| 7 | +xcube geoDB via 3rd-party services, such as |
| 8 | +[EuroDataCube](https://eurodatacube.com/) or [EO-TDL](https://www.eotdl.com/). |
| 9 | + |
| 10 | +If any problems occur regarding the installation, please create a new issue |
| 11 | +in the xcube geoDB |
| 12 | +[issue tracker](https://github.com/xcube-dev/xcube-geodb/issues). |
| 13 | + |
| 14 | +## 1. Installing the xcube geoDB user client |
| 15 | + |
| 16 | +This chapter describes the installation of the xcube geoDB client, which |
| 17 | +is the user interface and serves as a wrapper to accessing an existing |
| 18 | +xcube geoDB service. |
| 19 | + |
| 20 | +### Installation using the conda/mamba |
| 21 | + |
| 22 | +The xcube geoDB client is preferably installed into a conda environment. |
| 23 | +Ensure that you use Python 3 (>=3.6). The xcube geoDB client has not been |
| 24 | +tested with Python 2. |
| 25 | + |
| 26 | +The client is installed using conda (replace `conda` with `mamba` below if you |
| 27 | +are using mamba): |
| 28 | + |
| 29 | +```bash |
| 30 | +$ conda install -c conda-forge xcube_geodb |
| 31 | +$ conda activate xcube_geodb |
| 32 | +``` |
| 33 | + |
| 34 | +We strongly recommend using |
| 35 | +[`mamba`](https://github.com/mamba-org/mamba) instead of `conda`. |
| 36 | + |
| 37 | +### Installation from source |
| 38 | + |
| 39 | +There are frequent `conda` releases of the xcube geoDB, so usually it is not |
| 40 | +necessary to install from sources. However, if you want to try the cutting- |
| 41 | +edge version, use the following steps. |
| 42 | +Clone the repository using `git`: |
| 43 | + |
| 44 | +```bash |
| 45 | +$ git clone https://github.com/xcube-dev/xcube-geodb.git |
| 46 | +$ cd xcube-geodb |
| 47 | +``` |
| 48 | + |
| 49 | +You need to create the conda environment to install all dependencies |
| 50 | +(replace `conda` with `mamba` below if you are using mamba): |
| 51 | + |
| 52 | +```bash |
| 53 | +$ conda env create |
| 54 | +``` |
| 55 | + |
| 56 | +Once the environment has been created, activate the environment and |
| 57 | +install the xcube geoDB client (replace `conda` with `mamba` below if are |
| 58 | +using mamba): |
| 59 | + |
| 60 | +```bash |
| 61 | +$ conda activate xcube-geodb |
| 62 | +$ python setup.py develop |
| 63 | +``` |
| 64 | + |
| 65 | +## 2. Installation of the Database Backend |
| 66 | + |
| 67 | +This section describes how to set up the xcube geoDB database. The |
| 68 | +xcube geoDB core database consists of three software components: |
| 69 | + |
| 70 | +- an installation of a PostgreSQL database (version >= v13.19) |
| 71 | +- the PostGIS extension (version 3.x.x), installed in the database |
| 72 | +- the xcube geoDB extension, installed in the database |
| 73 | + |
| 74 | +The easiest way is to install the xcube geoDB extension into an existing PostGIS |
| 75 | +instance. There are ready-to-use PostGIS docker images, see |
| 76 | +[PostGIS docker image](https://registry.hub.docker.com/r/postgis/postgis/). |
| 77 | + |
| 78 | +To install the xcube geoDB extension, open a PostGreSQL console or a database |
| 79 | +GUI of your choice as super-user. Then copy and paste the contents of the geoDB |
| 80 | +[SQL script](https://github.com/xcube-dev/xcube-geodb/blob/main/xcube_geodb/sql/geodb.sql), |
| 81 | +replacing `VERSION_PLACEHOLDER` with the version provided in |
| 82 | +[version.py](https://github.com/xcube-dev/xcube-geodb/blob/main/xcube_geodb/version.py). |
| 83 | + |
| 84 | +## 3. Installation of the Postgrest RestAPI |
| 85 | + |
| 86 | +xcube geoDB offers access to the database via a RestAPI. xcube geoDB takes |
| 87 | +advantage of the wonderful Postgres REST API |
| 88 | +[PostgREST](https://github.com/PostgREST/postgrest). There are ready-to-use |
| 89 | +docker images that provide PostGREST, e.g. at |
| 90 | +https://hub.docker.com/r/postgrest/postgrest. PostGREST does not have many |
| 91 | +version requirements on the Postgres database; however, PostGREST ≥ v12.2.0 |
| 92 | +supports only those versions of Postgres that are officially supported |
| 93 | +(i.e., ≥ 13). |
| 94 | + |
| 95 | +To configure a PostgREST instance please refer to the |
| 96 | +[PostgREST configuration documentation](https://postgrest.org/en/stable/configuration.html). |
| 97 | +The configuration is straightforward; the only part of the configuration that |
| 98 | +is not is the authorization/authentication part, which is covered in detail |
| 99 | +in the next chapter. |
| 100 | + |
| 101 | +## 4. Authorization/Authentication |
| 102 | + |
| 103 | +The xcube geoDB infrastructure was developed to run on the |
| 104 | +[EuroDataCube](https://eurodatacube.com/) infrastructure. |
| 105 | + |
| 106 | +Therefore, we provide an example on how to configure PostgREST for proper |
| 107 | +authorization with an OAuth2-enabled Identity and Access Management (IAM) |
| 108 | +system (like Keycloak) using the `client_credentials` flow. The example uses |
| 109 | +Keycloak values and wording, but can be transferred to any OAuth2-enabled IAM. |
| 110 | + |
| 111 | +__Step 1__: Create an API in your IAM system |
| 112 | + |
| 113 | +Create a new API (Keycloak: Realm) in your IAM system. The users registered in |
| 114 | +this API can be enabled to access to your geoDB instance. In Keycloak, be sure |
| 115 | +to create a new Keystore provider of type `rsa` within the realm, that uses the |
| 116 | +algorithm `RS256`, and has the highest priority of all existing other |
| 117 | +keystores. Generate public/private Keypair, e.g. like this: |
| 118 | + |
| 119 | +```bash |
| 120 | +$ ssh-keygen -t rsa -b 4096 -m PEM -f winchester.key |
| 121 | +$ openssl rsa -in winchester.key -pubout -outform PEM -out winchester.key.pub |
| 122 | +``` |
| 123 | + |
| 124 | +Turn the public key into a JWK, e.g. using this |
| 125 | +[website](https://8gwifi.org/jwkconvertfunctions.jsp), and set the private key |
| 126 | +as the key of the Keystore provider you just configured: |
| 127 | + |
| 128 | + |
| 129 | + |
| 130 | +__Step 2__: Create an Application in your IAM API |
| 131 | + |
| 132 | +In Keycloak, create a client, choose Client Protocol `openid-connect`, and |
| 133 | +Access Type `confidential`. Enter a redirect URI that matches the URL of your |
| 134 | +service that provides the users with the access tokens. For the existing |
| 135 | +instances of xcube geoDB, this is the dedicated service `winchester`. In the |
| 136 | +simplest case, you need to set up a service that forwards the user |
| 137 | +login requests to your Keycloak instance, and returns the access token after |
| 138 | +successful login. That service must authenticate at Keycloak with the |
| 139 | +`client_id` and `client_secret` that can be retrieved from Keycloak. |
| 140 | +Furthermore, configure a mapper that maps the user role to the token claim |
| 141 | +that has been configured as `PGRST_ROLE_CLAIM_KEY` in your PostGREST |
| 142 | +configuration in section 3. The user role might be some user attribute. For |
| 143 | +the `winchester` client, this is done like this: |
| 144 | + |
| 145 | + |
| 146 | + |
| 147 | +Consequently, the PostGREST configuration item `PGRST_ROLE_CLAIM_KEY` is |
| 148 | +set to `'."https://geodb.brockmann-consult.de/dbrole"'`. Every user in the |
| 149 | +Realm has an attribute called `xcube_geodb_role`. |
| 150 | + |
| 151 | +__Step 3__: Use the client to authenticate |
| 152 | + |
| 153 | +The client can be configured using dotenv for your convenience. Add a .env file |
| 154 | +in your working directory. Add the following entries of you use client |
| 155 | +credentials: |
| 156 | + |
| 157 | +```dotenv |
| 158 | +GEODB_AUTH_CLIENT_ID = "the username as stored in Keycloak" |
| 159 | +GEODB_AUTH_CLIENT_SECRET = "the password as stored in Keycloak" |
| 160 | +GEODB_AUTH_MODE = "client-credentials" |
| 161 | +GEODB_AUTH_DOMAIN= "the URL of your login service" |
| 162 | +GEODB_API_SERVER_URL = "The postgrest API server URL" |
| 163 | +GEODB_API_SERVER_PORT = "The postgrest API server port" |
| 164 | +``` |
| 165 | + |
| 166 | +__Step 4__: Configure the PostgREST Service |
| 167 | + |
| 168 | +The PostgREST service needs a key to check the signature of the token. This is |
| 169 | +done using the `jwt-secret` in the PostGREST configuration. You can use |
| 170 | +symmetric encryption and store the key passphrase in `jwt-secret`, or use |
| 171 | +asymmetric encryption. Keycloak only supports asymmetric encryption. In that |
| 172 | +case, use the public part of the Keypair you generated in step 1 as value for |
| 173 | +`jwt-secret`. See alsothe |
| 174 | +[PostgREST documentation, section "JWT from Auth0"](https://postgrest.org/en/stable/auth.html#client-auth)): |
| 175 | + |
| 176 | +```dotenv |
| 177 | +db-uri = "postgres://user:password@localhost:5432/geodb" |
| 178 | +db-schema = "public, geodb_user_info" |
| 179 | +db-anon-role = "anonymous" |
| 180 | +jwt-secret = ""{\"alg\":\"RS256\",\"e\":\"AQAB\",\"key_ops\":[\"verify\"],\"kty\":\"RSA\",\"n\":\"aav7svBqEXAw-5D29LO...\"}"" |
| 181 | +``` |
| 182 | + |
| 183 | +## 5. Installation of the geoserver |
| 184 | + |
| 185 | +Data collections stored in the xcube geoDB can be published to a GeoServer |
| 186 | +instance, which can offer OGC WMS and WCS access to the data. In order to |
| 187 | +access such a server, the login server described section 4, step 2, |
| 188 | +needs access to a GeoServer instance using the credentials of a generic |
| 189 | +GeoServer user. The current xcube geoDB setup uses a custom docker image of |
| 190 | +based on the image `terrestris/geoserver:2.19.1`, with the `vectortiles` |
| 191 | +extension installed. It is published at |
| 192 | +[quay.io](https://quay.io/repository/bcdev/xcube-geoserv). |
| 193 | + |
| 194 | +**Careful**: When installing this docker image, you may run into CORS issues, |
| 195 | +and a wrong redirect to a http not https URL after login. Those issues have |
| 196 | +been resolved by adding the following settings to the GeoServer configuration: |
| 197 | + |
| 198 | +```yaml |
| 199 | + geoserver: |
| 200 | + geoserverCsrfWhitelist: xcube-geodb.brockmann-consult.de |
| 201 | + proxyBaseUrl: https://xcube-geodb.brockmann-consult.de/geoserver |
| 202 | +``` |
| 203 | +
|
| 204 | +These values are also configurable in the `web.xml` in |
| 205 | +`${GEOSERVER_DIR}/geoserver/WEB-INF`. |
| 206 | + |
| 207 | +For any more detailed information about installation, please refer to the |
| 208 | +[Dockerfile](https://github.com/terrestris/docker-geoserver/blob/master/Dockerfile) |
| 209 | +or the original |
| 210 | +[Installation instructions](https://docs.geoserver.org/stable/en/user/installation/index.html). |
| 211 | + |
| 212 | +Please be aware that the admin credentials should be changed after installation. |
0 commit comments