GIS Platform | On-Premise | Urbi Documentation

On-Premise GIS Platform service

GIS Platform is a web-based GIS solution. It supports the full cycle of working with spatial layers (vector and raster type): importing, creating, editing, customizing visualization, sharing, exporting, managing. It also enables performing geo analytical tasks using layers and geo tools provided.

GIS Platform comprises a frontend and a backend parts. They communicate with each other via RESTful API interface. All communications are protected through SSL (in other words, HTTPS is used).

GIS Platform service architecture

The frontend is used to interact with the GIS Platform service.

It provides the following web interfaces to access the service:

  1. Web UI GIS Tools is a set of tools for working with geospatial layers: updating the layer, editing information inside the layer (geometry and attributes), geoprocessing and making geo analysis of the geodata (building buffer zones or accessibility zones from the objects and making spatial queries), customizing the visualization of the layer, exporting the layer to Shape, GeoJSON, CSV formats, etc.
  2. Web UI Admin is a web application for managing service's configuration settings, users, and roles.

The frontend services can authenticate end users via login and password pair.

SPCore

The SPCore backend service implements all necessary geospatial logic. It is the primary backend service the frontend communicates with.

SPCore uses:

  • Apache ZooKeeper as a message queue for long-running tasks like buffer zone creation.

  • Other pre-deployed On-Premise services:

    • Maps service: the Tiles API is accessed to get a raster 2GIS Basemap.

    • Search service: the Geocoder API is accessed to work with geocoded data, and the Suggest API as accessed to provide suggestions on various objects on a map's overlay.

    • Navigation service: the Isochrone API is accessed via Navi-Front to get an area on the map that is reachable from a given point by car in a given amount of time.

    • Traffic Proxy service.

      If the service is deployed and configured to get real-time traffic data from 2GIS Traffic Servers, then end users and applications can use GIS Platform to plot colored traffic status on a map's overlay. SPCore interacts with the service in order to provide this capability.

SPCore stores:

  • The raster images in an S3-compatible storage. This allows, for example, to store the tiled satellite imagery for further usage.
  • The information on data layers, current configuration, users, and roles in PostgreSQL databases.

ZooKeeper

The ZooKeeper backend service acts as a message queue for long-running tasks like buffer zone creation.

Shared infrastructure:

  • S3-compatible storage for storing tiled raster images. The GIS Platform requires two separate buckets in this storage: one for previews, other for raster images.
  • PostgreSQL data storage for storing GIS Platform data. It is required to deploy PostgreSQL 12+ with PostGIS v3 extension.

On-Premise services:

Software on a machine used for deploying the GIS Platform service:

Detailed requirements for each service are listed in the Overview document. Additional information can be found in the Deployment considerations section of this document.

Important note:

All the steps listed below should be done from the machine that is connected to your Kubernetes cluster, and has Helm and other required software installed.

Do the following:

  1. Do the common deployment steps.

  2. Deploy Traffic Proxy service, if it is not deployed yet. See the Requirements section for details.

  3. Create the values-gis-platform.yaml configuration file:

    values-gis-platform.yaml

    dgctlDockerRegistry: <Docker Registry hostname and port>/2gis-on-premise
    
    external_hostname: <FQDN of the GIS Platform service>
    
    spcore:
        admin:
            email: <email of the administrator user>
            password: <password for the administrator user>
    
        catalog:
            url: <http(s)://FQDN of Catalog API endpoint>
            key: <a dedicated API service key to access Search APIs>
    
        jwt:
            token_admin: <token for the administrator user>
            token_key: <token for JWT cookies generation>
    
        pg:
            host: <hostname or IP address of PostgreSQL>
            port: <PostgreSQL port>
            user: <user name>
            password: <password>
            dbname: <database name>
    
        replicaCount: <number of the SPCore service replicas>
    
        resources:
            requests:
                cpu: 800m
                memory: 4096Mi
            limits:
                cpu: 800m
                memory: 4096Mi
    
        s3:
            access_key: <S3 access key>
            secret_key: <S3 secret key>
            host: <S3-compatible storage endpoint>
            region: <S3 region>
            bucket: <bucket for raster images>
            preview_bucket: <bucket for previews>
    
    zookeeper:
        replicaCount: <number of the ZooKeeper service replicas, from 1 to 3>
    
        resources:
            requests:
                cpu: 300m
                memory: 1024Mi
            limits:
                cpu: 500m
                memory: 2048Mi
    
    portal:
        replicaCount: <number of Portal service replicas>
    
        max_body_size: 100m
    
        resources:
            requests:
                cpu: 100m
                memory: 512Mi
            limits:
                cpu: 100m
                memory: 512Mi
    
    ingress:
        hosts:
            - host: gis-platform.host
    

    Where:

    1. dgctlDockerRegistry: your Docker Registry endpoint where On-Premise services' images reside.

    2. external_hostname: FQDN of the GIS Platform service. Web interfaces will be available on this FQDN via HTTPS.

    3. spcore: settings for the SPCore backend service.

      1. admin: administrator's credentials settings.

        1. email: email of the administrator user.
        2. password: password for the administrator user.
      2. catalog: access settings for the Catalog API service. This service interacts with Geocoder API and Suggest API.

        1. url: FQDN of Catalog API endpoint. It must be specified in the http(s)://example.com form, without trailing slash /. This URL should be accessible from all the pods within your Kubernetes cluster.
        2. key: a dedicated service API key to access the search services. See the API Keys service documentation for details.
      3. jwt: JSON Web Tokens (JWT) generation settings.

        1. token_admin: Token for the administrator user, so they can log in with it. Must be a string of 32 or more random characters.
        2. token_key: Token for JWT cookies generation. Must be a string of 32 or more random characters.
      4. pg: access settings for the PostgreSQL server.

        1. host: hostname or IP address of the PostgreSQL server.
        2. port: listening port of the PostgreSQL server. For example, 5432.
        3. 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.
        4. dbname: database name.
      5. replicaCount: number of the SPCore service replicas.

      6. resources: computational resources settings for service. See the minimal requirements table for the actual information about recommended values.

      7. s3: S3 storage settings (for storing GIS Platform tiles data).

        1. access_key: S3 access key.
        2. secret_key: S3 secret key.
        3. host: FQDN of S3-compatible storage endpoint.
        4. region: S3 region.
        5. bucket: bucket for storing raster images.
        6. preview_bucket: bucket for storing previews.
    4. zookeeper: settings for the ZooKeeper backend service.

      1. replicaCount: number of the ZooKeeper service replicas. Value of this setting can vary from 1 to 3.
      2. resources: computational resources settings for service. See the minimal requirements table for the actual information about recommended values.
    5. portal: settings for the Portal frontend service.

      1. replicaCount: number of the Portal service replicas.
      2. max_body_size: maximum size of a file that can be uploaded via Portal web UI.
      3. resources: computational resources settings for service. See the minimal requirements table for the actual information about recommended values.
    6. 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.

  4. 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.0.3 --atomic --wait-for-jobs --values ./values-gis-platform.yaml gis-platform 2gis-on-premise/gis-platform --set spcore.reset_cluster=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.
    
  5. Do the initial configuration of the GIS Platform service:

    1. Set the Bash environment variables:

      export GIS_PLATFORM_URL=<external_hostname from values-gis-platform.yaml>
      export GIS_PLATFORM_PASS=<spcore.admin.password from values-gis-platform.yaml>
      export GIS_PLATFORM_TILES_API=<http(s)://TILES_API_FQDN>
      export GIS_PLATFORM_TRAFFIC_API=<http(s)://TRAFFIC_PROXY_FQDN>
      
    2. Run the configuration script:

      helm pull --untar 2gis-on-premise/gis-platform && \
      cd gis-platform/gis-platform-config && \
      ./configure.sh
      

      Wait for the script to complete.

      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.

  6. Perform the basic healthcheck of the GIS Platform service:

    1. Open the external_hostname address from a browser.

    2. Log in using the following credentials:

      1. User name: admin.
      2. Password: the value of the spcore.admin.password setiing.

    You should be successfully logged into the Web UI.

  7. 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.0.3 --atomic --wait-for-jobs --values ./values-gis-platform.yaml gis-platform 2gis-on-premise/gis-platform
    

    Important note:

    This command differs from the similar comand above: it lacks the --set spcore.reset_cluster=true argument, because now the services shouldn't be resetted. Do not use the command from the step 2 (initial deployment).

To update the GIS Platform service, execute the following command:

helm upgrade --version=1.0.3 --atomic --wait-for-jobs --values ./values-gis-platform.yaml gis-platform 2gis-on-premise/gis-platform

To test the operability of the services:

  1. Open the external_hostname address from a browser.

  2. Log in using the following credentials:

    1. User name: admin.
    2. Password: the value of the spcore.admin.password setiing.

You should be successfully logged into the Web UI.