Installing GIS Platform
Important note:
All passwords and keys in this section are given for illustration purposes.
During a real installation, it is recommended to use more complex and reliable passwords.
1. Before installing
-
Consider getting familiar with:
-
Make sure the necessary preparation steps are completed:
-
Collect the necessary information that was set or retrieved on previous steps:
Object Example value How to get value Docker Registry mirror endpoint docker.storage.example.local:5000
See Fetching installation artifacts API Keys service endpoint http://keys-api
See Installing API Keys service Tiles API endpoint http://tiles-api
See Installing maps API Catalog APIs endpoint http://catalog-api
See Installing search API Traffic API Proxy endpoint http://traffic-proxy
See Installing Traffic API Proxy API Keys CATALOG_KEY
See Installing API Keys service -
Make sure that the resource requirements specified in the Helm chart are met. For more information on how to do this, refer to the System requirements document.
Note
These storage requirements are calculated for the use case of storing huge volume of high-resolution tiled images, for example, satellite imagery. If you do not plan to store such type of data, then storage requirements may be lowered.
Note
Contents of the Helm chart described in this chapter are relevant for the latest On-Premise version (see Release notes). To find parameters for earlier versions, open values.yaml on GitHub and enter the required version number (for example, 1.18.0) in the tag switcher on the left.
-
Choose the domain name for the service.
Example:
gis-platform.example.com
2. Prepare infrastructure required for the service
Configure PostgreSQL
Place a PostgreSQL cluster with the domain name gis-platform-postgresql.storage.example.local
in the private network. This instruction assumes that the cluster works on the standard port 5432
.
Configure the PostgreSQL cluster for usage as a storage:
-
Connect to the cluster a superuser (usually
postgres
). -
Create a database user that will be used for the service. Set a password for the user.
create user gisplatform_superuser password 'GISPLATFORM_Db_Owner_Password_1234';
-
Create a database owned by this user.
create database onpremise_gisplatform owner gisplatform_superuser;
-
Install the PostGIS extension.
\c onpremise_gisplatform CREATE EXTENSION postgis WITH SCHEMA public;
Configure S3 storage
Place an S3 compatible storage (e.g., Ceph) with the domain name gis-platform-s3.storage.example.local
in the private network. This instruction assumes that the storage works on the standard port 80
.
Configure the S3 compatible storage:
-
Create a user that will be used for the service. Remember the credentials for the user.
Example:
- Access key:
PHEI4AHTHEETHAHXEEGE
- Secret key:
aiw6ahlaeshahngaiJaebie6aeth0aiV2pucuey1
- Access key:
-
Create a zone group (region) that will be used for the service.
Example:
US
-
Choose bucket names that will be used for the service.
Example:
- Bucket for the main data:
spstatic
- Bucket for the session data:
spsession
- Bucket for the main data:
3. Install GIS Platform service
-
Create a Helm configuration file. See here for more details on the available settings.
The example is prefilled with the necessary data collected on previous steps.
values-gis-platform.yaml
dgctlDockerRegistry: docker.storage.example.local:5000 external_hostname: gis-platform.example.com spcore: admin: email: admin@example.com password: Oi3ha5eiL9OquooZ catalog: url: http://catalog-api key: CATALOG_KEY jwt: tokenAdmin: xeep2nahjooGhaa3ke8ahy2moogh7ieB tokenKey: aihu6YaiM7owaequohpheizahvoh4go5 pg: host: gis-platform-postgresql.storage.example.local port: 5432 user: gisplatform_superuser password: GISPLATFORM_Db_Owner_Password_1234 dbname: onpremise_gisplatform replicaCount: 16 resources: requests: cpu: 800m memory: 4096Mi limits: cpu: 800m memory: 4096Mi s3: host: gis-platform-s3.storage.example.local access_key: PHEI4AHTHEETHAHXEEGE secret_key: aiw6ahlaeshahngaiJaebie6aeth0aiV2pucuey1 region: US bucket: spstatic session_bucket: spsession zookeeper: replicaCount: 2 resources: requests: cpu: 300m memory: 1024Mi limits: cpu: 500m memory: 2048Mi portal: replicaCount: 2 max_body_size: 100m resources: requests: cpu: 100m memory: 512Mi limits: cpu: 100m memory: 512Mi ingress: enabled: true className: nginx hosts: - host: gis-platform.example.com paths: - path: / pathType: Prefix tls: [] #- hosts: # - gis-platform.example.com # secretName: secret.tls
Where:
-
dgctlDockerRegistry
: your Docker Registry endpoint where On-Premise services' images reside. -
external_hostname
: FQDN of the GIS Platform service. Web interfaces will be available on this FQDN via HTTPS. -
spcore
: settings for the SPCore backend service.-
admin
: administrator's credentials.email
: email of the administrator user.password
: password for the administrator user.
-
catalog
: access settings for the Catalog APIs service. This service interacts with Geocoder API and Suggest API.url
: FQDN of Catalog APIs endpoint. It must be specified in thehttp://catalog-api
form, without trailing slash/
. This URL should be accessible from all the pods within your Kubernetes cluster.key
: a dedicated service token to access the Search services. See the API Keys service documentation for details.
-
jwt
: JSON Web Tokens (JWT) generation settings.tokenAdmin
: token for the administrator user, which is used to log in to the administrator web interface. Must be a string of 32 or more random characters.tokenKey
: token for JWT cookies generation. Must be a string of 32 or more random characters.
-
pg
: access settings for the PostgreSQL server.host
: hostname or IP address of the PostgreSQL server.port
: listening port of the PostgreSQL server.user
andpassword
: credentials for accessing the database specified in thedbname
setting. The user must be the owner of this database or a superuser.dbname
: database name.
-
replicaCount
: number of the SPCore service replicas. -
resources
: computational resources settings for the service. To find out recommended resource values, see Computational resources. -
s3
: S3 storage settings (for storing GIS Platform tiles data).access_key
: S3 access key.secret_key
: S3 secret key.host
: FQDN of S3 compatible storage endpoint.region
: S3 region.bucket
: bucket for storing raster images.session_bucket
: bucket for storing previews.
-
-
zookeeper
: settings for the ZooKeeper backend service.replicaCount
: number of the ZooKeeper service replicas. Value of this setting can vary from 1 to 3.resources
: computational resources settings for the service. To find out recommended resource values, see Computational resources.
-
portal
: settings for the Portal frontend service.replicaCount
: number of the Portal service replicas.max_body_size
: maximum size of a file that can be uploaded via Portal web UI.resources
: computational resources settings for the service. To find out recommended resource values, see Computational resources.
-
ingress
: configuration of the Ingress resource. Adapt it to your Ingress installation. The URL specified in theingress.hosts.host
parameter should be accessible from the outside of your Kubernetes cluster, so that users in the private network can browse the URL.
-
-
Do the initial deployment of the GIS Platform service.
During this operation the following will happen:
- The
spcore.replicaCount
setting value will be forced to1
. - The services will be reset to their initial states.
- Necessary data structures will be initialized, databases will be migrated.
Do the initial deployment with Helm using created
values-gis-platform.yaml
configuration file.helm upgrade --install --version=1.32.0 --atomic --wait-for-jobs --values ./values-gis-platform.yaml gis-platform 2gis-on-premise/gis-platform --set spcore.resetCluster=true
Then wait for the process to complete. When initial deployment is complete, you will see the similar message in the
spcore
pod's logs:Now listening on: http://[::]:5051 Application started. Press Ctrl+C to shut down.
- The
-
Do the initial configuration of the GIS Platform service:
-
Set the environment variables:
export GIS_PLATFORM_URL=https://gis-platform.example.com # value of external_hostname export GIS_PLATFORM_PASS=Oi3ha5eiL9OquooZ # value of spcore.admin.password export GIS_PLATFORM_TILES_API=https://tiles-api.example.com export GIS_PLATFORM_TRAFFIC_API=https://traffic-proxy.example.com
-
Run the configuration script:
helm pull --untar 2gis-on-premise/gis-platform cd gis-platform/gis-platform-config ./configure.sh
Note:
Starting with the version 1.1.0, it is possible to specify the
-k
argument when running theconfigure.sh
script.This argument allows skipping the connection security verification when connecting to a server via HTTPS. Any errors that may occur if untrusted SSL certificate (for example, a self-signed one) is used by GIS Platform services will be ignored.
-
-
Perform the basic health check of the GIS Platform service:
-
Open the
https://gis-platform.example.com
address in a browser (the value of theexternal_hostname
setting). -
Log in using the following credentials:
- User name:
admin
. - Password: the value of the
spcore.admin.password
setting.
- User name:
You should be successfully logged into the Web UI.
-
-
After the successful log in attempt, do the second phase of the deployment with Helm using created
values-gis-platform.yaml
configuration file.helm upgrade --install --version=1.32.0 --atomic --wait-for-jobs --values ./values-gis-platform.yaml gis-platform 2gis-on-premise/gis-platform
Important note:
This command differs from the similar command above: it lacks the
--set spcore.resetCluster=true
argument, because now the services should not be reset. Do not use the command from the step 2 (initial deployment).
What's next?
-
Find out how to update the service:
-
Install other On-Premise products: