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:
- GIS Platform service documentation
- On-Premise solution architecture
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
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

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 the http://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 and password: credentials for accessing the database specified in the dbname 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 the ingress.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:
1. The spcore.replicaCount setting value will be forced to 1.
2. The services will be reset to their initial states.
3. 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.31.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.
```
Do the initial configuration of the GIS Platform service:
1. 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
```
2. 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 the configure.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:
1. Open the https://gis-platform.example.com address in a browser (the value of the external_hostname setting).
2. Log in using the following credentials:
  1. User name: admin.
  2. Password: the value of the spcore.admin.password setting.
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.31.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:
- Updating GIS Platform
Install other On-Premise products: