Maps | On-Premise | 2GIS Documentation
On-Premise

On-Premise Maps services

Maps services allow displaying 2GIS maps in web applications and websites.

This article describes how to deploy and configure the Maps services in your environment. To learn how to use the JavaScript library provided by the Maps services, see MapGL JS API Overview.

On-premise Maps services architecture

Maps can be deployed in two different configurations:

  1. With the MapGL JS API and the Tiles API services.

    In this configuration, MapGL JS API service implements a JavaScript API for displaying maps using vector tiles from the Tiles API service.

    To use the API, it is necessary to download the main library file (api.js) and the default (light) style for the map (the style directory) from the web server.

    A Traffic Proxy service is used by MapGL JS API to get real-time traffic data from 2GIS Traffic Servers. MapGL JS service uses the data to plot colored traffic status on a map's overlay.

  2. With the Tiles API service only.

    In this configuration, Tiles API serves raster tiles.

    This configuration is designed to be used primarily with the GIS Platform On-Premise service that consumes the raster tiles.

    However, it is possible for any application, that is able to work with raster tiles, to directly access Tiles API, and use the tiles.

Each deployment configuration requires the Tiles API service that provides an API to access and display map tiles. A tile is a square image of a part of the map (example tiled map). With tiles it is possible to render only visible part of map, fetching the necessary tiles when the map is either zoomed or moved. Therefore, an application consumes less memory when working with the map.

For detailed overview of the On-Premise solution architecture, see the Overview document.

If you plan to deploy the configuration with the MapGL JS API and the Tiles API services:

  • Services:

    • MapGL JS API service
    • Tiles API service that is configured to serve vector tiles.
  • Shared infrastructure:

    • Traffic Proxy service that provides the traffic data in vector format.
    • Apache Cassandra data storage for storing tiles for Tiles API service.

If you plan to deploy the configuration with the Tiles API service only:

  • Services:

    • Tiles API service that is configured to serve raster tiles.
  • Shared infrastructure:

    • Apache Cassandra data storage for storing tiles for Tiles API 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.

Note:

The Ingress configuration in configuration files is sample and for reference only. Adapt this configuration to your needs and Ingress installation.

Do the following:

  1. Do the common deployment steps.

    Note:

    Do not forget to write down the path to a manifest file, it will be required to deploy the services.

  2. Deploy Tiles API service.

  3. Deploy Traffic Proxy service, if necessary. See the Requirements section for details.

  4. Deploy MapGL JS API service, if necessary. See the Requirements section for details.

  1. Choose the Tiles API flavor to deploy: Tiles API for the vector tiles or Tiles API for the raster tiles.

  2. Create the values-tiles.yaml configuration file:

    values-tiles.yaml

    dgctlDockerRegistry: <Docker Registry hostname and port>/2gis-on-premise
    
    dgctlStorage:
        host: <Deployment Artifacts Storage endpoint>
        bucket: <Deployment Artifacts Storage bucket>
        accessKey: <The bucket access key>
        secretKey: <The bucket secret key>
        manifest: <Path to the manifest file>
    
    serviceName: <name that depends on Tiles API flavor>
    type: <Tiles API flavor>
    
    cassandra:
        hosts:
            - <IP address of Apache Cassandra host>
            - ...
            - <IP address of Apache Cassandra host>
    
        replicaFactor: 3
        consistencyLevelRead: LOCAL_QUORUM
        consistencyLevelWrite: LOCAL_QUORUM
        credentials:
            password: "cassandra"
            user: "cassandra"
    
    importer:
        workerNum: 20
        writerNum: 8
        workerResources:
            requests:
                cpu: 256m
                memory: 512Mi
            limits:
                cpu: 2
                memory: 2048Mi
    
    api:
        pdb:
            enabled: false
        ingress:
            annotations:
                cert-manager.io/cluster-issuer: <Issuer name>
            enabled: true
            hosts:
                - host: <Domain name for Tiles API service>
                    paths:
                        - path: /
                          pathType: Prefix
            tls:
                - hosts:
                    - <Domain name for Tiles API service>
                secretName: tls-tiles-api
    
    proxy:
        access:
            enabled: <true or false>
            host: <API Keys endpoint>
            token: <service API key>
    

    Where:

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

    2. dgctlStorage: Deployment Artifacts Storage settings.

      1. Fill in the common settings to access the storage: endpoint, bucket, and access credentials.
      2. manifest: fill in the path to the manifest file in the manifests/1640661259.json format. This file contains the description of pieces of data that the service requires to operate.
    3. serviceName: name of the service.

      1. tiles-api-webgl: for Tiles API with vector tiles support.
      2. tiles-api-raster: for Tiles API with raster tiles support.
    4. type: flavor of the service.

      1. Do not specify this parameter for Tiles API with vector tiles support.
      2. raster: for Tiles API with raster tiles support.
    5. cassandra: the Apache Cassandra data storage settings.

      1. hosts: an array of the one of more IP adresses of the Apache Cassandra installation that you have.
      2. replicaFactor: replication factor. Adjust this setting in accordance with the installation.
      3. If necessary, adjust consistency level settings in accordance with the installation. See the Apache Cassandra documentation for details.
      4. credentials: credentials to authenticate in Apache Cassandra with. Default values: cassandra/cassandra.
    6. importer: the Kubernetes Importer job's worker settings.

      1. workerNum: number of workers (parallel import processes).
      2. writerNum: number of write processes per one worker.

      Note:

      When deploying the Tiles API with raster tiles support, consider to tune down the values of workerNum (by default: 20) and writerNum (by default: 8) settings.

      Import of raster tiles data may take a significant time to complete, and usage of relatively high default settings may result in cancelling the job due to timeout.

      1. workerResources: computational resources settings for workers. See the minimal requirements table for the actual information about recommended values.

      See the Overview document for details about how the Import job operates.

    7. api: the API backend service.

      1. pdb.enabled: enables the protection of the service with Pod Disruption Budget.
      2. ingress: sample configuration of the Ingress resource. Adapt it to your Ingress installation. The URL specified in the api.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.
    8. proxy: the API Keys service settings. Use these settings if you want to restrict end-user access to the Tiles API service.

      1. access.enabled: flag that controls whether keys checking for access limiting is enabled.
      2. url: URL of the API Keys service's endpoint. This URL should be accessible from all the pods within your Kubernetes cluster.
      3. token: a dedicated service API key for the Tiles API service. Fetch the key by executing keysctl utility.
  3. Deploy the service with Helm using created values-tiles.yaml configuration file.

    Important note:

    When doing a deployment, the Kubernetes Importer job will reinitialize the Apache Cassandra keyspace in the Apache Cassandra installation specified in the values-tiles.yaml configuration.

    This means that all data in this keyspace, if exists, will be completely replaced with the data from the Deployment Artifacts Storage.

    Existing data is preserved for a short amount of time only if you do a update, not initial deployment.

    helm upgrade --install --atomic --values ./values-tiles.yaml tiles-api 2gis-on-premise/tiles-api
    

    Kubernetes Importer job will fetch the required data from the Deployment Artifacts Storage and do the import of the data into Apache Cassandra. Then Helm will deploy the service.

  1. Create the values-mapgl.yaml configuration file:

    values-mapgl.yaml

    dgctlDockerRegistry: <Docker Registry hostname and port>/2gis-on-premise
    
    env:
        MAPGL_HOST: <Domain name for MapGL JS API service>
        MAPGL_TILES_API: <Domain name of the Tiles API service>
        MAPGL_KEYSERVER: <Domain name of the API Keys service>
        MAPGL_TRAFFICSERVER: <Domain name of the Traffic Proxy service>
    
    resources:
        requests:
            cpu: 30m
            memory: 32M
        limits:
            cpu: 100m
            memory: 64M
    
    ingress:
        annotations:
            cert-manager.io/cluster-issuer: <Issuer name>
        enabled: true
        hosts:
            - host: <Domain name for MapGL JS API service>
                paths:
                    - path: /
                      pathType: Prefix
        tls:
            - hosts:
                - <Domain name for MapGL JS API service>
            secretName: mapgl-js-api
    

    Where:

    1. dgctlDockerRegistry: your Docker Registry endpoint where On-Premise services' images reside.
    2. env: environment variables.
      1. MAPGL_HOST: domain name for the service. Your applications should use this domain name or IP address to communicate with the On-Premise Maps service.
      2. MAPGL_TILES_API: domain name of the deployed Tiles API service.
      3. MAPGL_KEYSERVER: domain name of the API Keys service.
      4. MAPGL_TRAFFICSERVER: domain name of the Traffic Proxy service.
    3. resources: computational resources settings for workers. See the minimal requirements table for the actual information about recommended values.
    4. ingress: sample configuration of the Ingress resource. Adapt it to your Ingress installation.
  2. Deploy the service with Helm using created values-mapgl.yaml configuration file.

    helm upgrade --install --version=1.0.3 --atomic --values ./values-mapgl.yaml mapgl-js-api 2gis-on-premise/mapgl-js-api
    

For this service:

  • You can update both data and services, or only services.
  • When updating data, the current data will be replaced with the new data only after a series of healthchecks.

See the Overview document for details about how the update process is organized.

To update the service, execute one of the following command:

  • To update both data and the service:

    helm upgrade --version=1.0.3 --atomic --values ./values-tiles.yaml tiles-api 2gis-on-premise/tiles-api
    
  • To update the service only:

    helm upgrade --version=1.0.3 --atomic --values ./values-tiles.yaml tiles-api 2gis-on-premise/tiles-api --set importer.enabled=false
    

To update the service, execute the following command:

helm upgrade --version=1.0.3 --atomic --values ./values-mapgl.yaml mapgl-js-api 2gis-on-premise/mapgl-js-api

To test the operability of the MapGL JS API service and Tiles API service for vector tiles, do one of the following:

  1. Open the domain name or IP address of the service in your browser:

    http://MAPGL_HOST
    
  2. Write a code for displaying the sample map, then open it from a browser:

    <html>
        <head>
            <title>MapGL JS API. On-Premise</title>
            <style>
                #map {
                    width: 100%;
                    height: 100%;
                }
            </style>
        </head>
    
        <body>
            <div id="map"></div>
            <script src="//MAPGL_HOST/api.js"></script>
            <script>
                const map = new mapgl.Map('map', {
                    center: [55.31878, 25.23584],
                    zoom: 13,
                    style: '//MAPGL_HOST/style/',
                    styleOptions: {
                        iconsPath: '//MAPGL_HOST/style/images/',
                        fontsPath: '//MAPGL_HOST/style/fonts/',
                    },
                    useRtlTextPlugin: 'always-on',
                    zoom: 13,
                });
            </script>
        </body>
    </html>
    

Note:

This code slightly differs from the code placed in MapGL JS API documentation. If you use the code examples from the documentation, do not forget to adapt them to your On-Premise Maps service deployment, as shown above.

A sample vector map should be displayed. This map uses vector tiles served by the Tiles API service.

To verify that Tiles API can serve raster tiles, you can open the following URL in your browser:

http://TILES_API_PUBLIC_HOST/tiles?x=2602&y=1736&z=12

A sample raster tile should be displayed.