Skip to main content

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​

  1. Consider getting familiar with:

  2. Make sure the necessary preparation steps are completed:

    1. Preparation for installation
    2. Fetching installation artifacts
    3. Installing License service
    4. Installing API Keys service
    5. Installing maps API
    6. Installing search API
    7. Installing Traffic API Proxy

  3. Collect the necessary information that was set or retrieved on previous steps:

    ObjectExample valueHow to get value
    Docker Registry mirror endpointdocker.storage.example.local:5000See Fetching installation artifacts
    API Keys service endpointhttp://keys-apiSee Installing API Keys service
    Tiles API endpointhttp://tiles-apiSee Installing maps API
    Catalog APIs endpointhttp://catalog-apiSee Installing search API
    Traffic API Proxy endpointhttp://traffic-proxySee Installing Traffic API Proxy
    API KeysCATALOG_KEYSee Installing API Keys service

  4. 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.

  5. Choose the domain name for the service.

    Example: gis-platform.example.com

2. Prepare infrastructure​

Configure PostgreSQL​

Place a PostgreSQL cluster with the domain name gis-platform-postgresql.storage.example.local in the private network. It is assumed that the cluster works on the standard port 5432.

Configure the PostgreSQL cluster for usage as a storage:

  1. Connect to the cluster as a superuser (usually postgres).

  2. Create a database user and set a password for the user:

    create user gisplatform_superuser password 'GISPLATFORM_Db_Owner_Password_1234';

  3. Create a database owned by this user:

    create database onpremise_gisplatform owner gisplatform_superuser;

  4. Install the PostGIS extension for PostgreSQL.

  5. Enable 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. It is assumed that the storage works on the standard port 80.

Configure the S3 compatible storage:

  1. Create a user that will be used for the service. Remember the credentials for the user.

    Example:

    • Access key: PHEI4AHTHEETHAHXEEGE
    • Secret key: aiw6ahlaeshahngaiJaebie6aeth0aiV2pucuey1

  2. Create a zone group (region) that will be used for the service.

    Example: US

  3. 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​

  1. 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: endpoint of your Docker Registry with the images of the On-Premise services.

    • 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: host name 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.

  2. 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.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.

  3. 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.

  4. 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.

  5. 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?​