Maps API | On-Premise | 2GIS Documentation

Installing maps API

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. 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 Traffic API Proxy
  3. 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
    Kubernetes secret for accessing Docker Registry onpremise-registry-creds See Fetching installation artifacts
    Installation artifacts S3 storage domain name artifacts.example.com See Fetching installation artifacts
    Bucket name for installation artifacts onpremise-artifacts See Fetching installation artifacts
    Installation artifacts access key AKIAIOSFODNN7EXAMPLE See Fetching installation artifacts
    Installation artifacts secret key wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY See Fetching installation artifacts
    Path to the manifest file manifests/1640661259.json See Fetching installation artifacts
    License service endpoint https://license See Installing License service
    API Keys service endpoint http://keys-api See Installing API Keys service
    Traffic API Proxy endpoint http://traffic-proxy See Installing Traffic API Proxy
    Service tokens TILES_TOKEN See Installing API Keys service
  4. Make sure that the resource requirements specified in the Helm charts are met:

    For more information on how to do this, refer to the System requirements document.

    Note

    Contents of Helm charts described in this chapter are relevant for the latest On-Premise version (see Release notes). To find parameters for earlier versions, open the required values.yaml on GitHub and enter the required version number (for example, 1.18.0) in the tag switcher on the left.

  5. Choose domain names for the services.

    Example:

    • Domain name for Tiles API: tiles-api.example.com
    • Domain name for MapGL JS API: mapgl-js-api.example.com
    • Domain name for Floors API: floors.example.com

Place one or multiple instances of an Apache Cassandra in the private network.

It is recommended to allow JMX access to Apache Cassandra to enable removing storage snapshots (see Updating Tiles API service).

If Cassandra's security settings do not allow automatic creation of keyspaces, you should manually create a keyspace for storing tile data.

Example:

  • Hosts:
    • tiles-cassandra-1.storage.example.local
    • tiles-cassandra-2.storage.example.local
    • tiles-cassandra-3.storage.example.local
  • Username: cassandrauser
  • Password: CASSANDRAPASSWORD-DWTYB05URKZJEDDN
  • JMX username: jmxuser
  • JMX password: JMXPASSWORD-MNZLQTFH0MDDHIX8
  1. Select which variant of Tiles API you want to install: for vector or raster tiles.

  2. 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-tiles.yaml
    dgctlDockerRegistry: docker.storage.example.local:5000
    
    dgctlStorage:
        host: artifacts.example.com
        secure: false
        bucket: onpremise-artifacts
        accessKey: AKIAIOSFODNN7EXAMPLE
        secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
        manifest: manifests/1640661259.json
    
    warningText: License expiring in %d days.\nPlease contact your account manager.\n%s
    errorText: License expired.\nPlease contact your account manager.\n%s
    emailManager: on-premise@2gis.com
    
    types:
        - kind: web
        - kind: web
          subtype: immersive
    
    cassandra:
        hosts:
            - tiles-cassandra-1.storage.example.local
            - tiles-cassandra-2.storage.example.local
            - tiles-cassandra-3.storage.example.local
        replicaFactor: 3
        consistencyLevelRead: LOCAL_QUORUM
        consistencyLevelWrite: LOCAL_QUORUM
        credentials:
            user: cassandrauser
            password: CASSANDRAPASSWORD-DWTYB05URKZJEDDN
            jmxUser: jmxuser
            jmxPassword: JMXPASSWORD-MNZLQTFH0MDDHIX8
        ssl:
            enabled: false
    
    importer:
        workerNum: 20
        writerNum: 8
        workerResources:
            requests:
                cpu: 256m
                memory: 512Mi
            limits:
                cpu: 2
                memory: 2048Mi
        cleaner:
            enabled: true
            limit: 3
        clearSnapshots: true
    
    api:
        imagePullSecrets: [onpremise-registry-creds]
        pdb:
            enabled: false
        ingress:
            enabled: true
            className: nginx
            hosts:
                - host: tiles-api.example.com
                  paths:
                      - path: /
                        pathType: Prefix
            tls: []
            #- hosts:
            #  - tiles-api.example.com
            #  secretName: secret.tls
    
    proxy:
        access:
            enabled: true
            url: http://keys-api
            token: TILES_TOKEN
    
    license:
        url: 'https://license'
        retryPeriod: 30s
    
    customCAs:
        bundle: ''
        # bundle: |
        #   -----BEGIN CERTIFICATE-----
        #   ...
        #   -----END CERTIFICATE-----
        certsPath: ''
    

    Where:

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

    • dgctlStorage: installation artifacts storage settings.

      • Fill in the common settings to access the storage: endpoint, bucket, and access credentials.
      • secure: whether to use HTTPS for interacting with the S3-compatible storage. Default value: false.
      • manifest: 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. See Installation artifacts lifecycle.
    • warningText: warning message about upcoming blocking when working with raster tiles. Should contain: %d — placeholder for the number of days before the full block, %s — placeholder for the account manager's contact.

    • errorText: message about full blocking when working with raster tile. Should contain %s — placeholder for the account manager's contact.

    • emailManager: account manager contact that is used in messages when working with raster tiles.

    • types: an array of the one of more tile types the service will provide.

      • types[0].kind: defines the type of tiles to be returned. Possible values are: web, raster, native.
        • web — vector tiles for MapGL JS API.
          • subtype: immersive — vector tiles subtype to display 3D models on the map.
        • raster — raster tiles.
        • native — vector tiles for Mobile SDK.
    • cassandra: the Apache Cassandra data storage settings.

      • hosts: an array of the one of more IP addresses of the Apache Cassandra installation.
      • replicaFactor: replication factor. Adjust this setting in accordance with the installation.
      • If necessary, adjust consistency level settings in accordance with the installation.
      • credentials: authentication credentials. The user and password values are necessary, while jmxUser and jmxPassword are only used for clearing snapshots (see Updating Tiles API service). Default value for each setting is cassandra.
      • ssl: SSL configuration for accessing Apache Cassandra.
        • enabled: enable it if Apache Cassandra uses SSL for client connections. By default, false (disabled).
    • importer: the Kubernetes Importer job's worker settings.

      • workerNum: number of workers (parallel import processes).

      • 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 (default: 20) and writerNum (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.

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

      • cleaner and clearSnapshots: settings for automatic deletion of older data. See Updating Tiles API service for more details.

      See the Installation artifacts lifecycle document for details about how the Import job operates.

    • api: the API backend service.

      • imagePullSecrets: Kubernetes Secrets for accessing the Docker Registry endpoint where On-Premise services' images reside.
      • pdb.enabled: enables the protection of the service with Pod Disruption Budget.
      • ingress: 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.
    • proxy: the API Keys service settings. Use these settings if you want to restrict end-user access to the Tiles API service.

      • access.enabled: flag that controls whether keys checking for access limiting is enabled.
      • access.url: URL of the API Keys service's endpoint. This URL should be accessible from all the pods within your Kubernetes cluster.
      • access.token: a dedicated service token for the Tiles API service. Fetch the key by executing keysctl utility.
    • license: the License service settings.

      • url: License service URL address. Example: https://license.
      • retryPeriod: how often Tiles API should try to update license status if it is failing to get it.
    • customCAs: custom certificates settings.

      • bundle: text representation of a certificate in the X.509 PEM public-key format.
      • certsPath: bundle mount directory in the container.
  3. Deploy the service with Helm using created values-tiles.yaml configuration file.

    helm upgrade --install --version=1.20.2 --atomic --wait --timeout 7200s --values ./values-tiles.yaml tiles-api 2gis-on-premise/tiles-api
    

    Kubernetes Importer job will fetch the required data from the Installation Artifacts Storage and do the import of the data into Apache Cassandra. Then Helm will deploy the 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-mapgl.yaml
    dgctlDockerRegistry: docker.storage.example.local:5000
    
    env:
        MAPGL_HOST: mapgl-js-api.example.com
        MAPGL_TILES_API: tiles-api.example.com
        MAPGL_KEYSERVER: keys.example.com
        MAPGL_TRAFFICSERVER: traffic-proxy.example.com
        MAPGL_FLOORSSERVER: floors.example.com
    
    resources:
        requests:
            cpu: 30m
            memory: 32M
        limits:
            cpu: 100m
            memory: 64M
    
    ingress:
        enabled: true
        className: nginx
        hosts:
            - host: mapgl-js-api.example.com
              paths:
                  - path: /
                    pathType: Prefix
        tls: []
        #- hosts:
        #  - mapgl-js-api.example.com
        #  secretName: secret.tls
    

    Where:

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

    • imagePullSecrets: Kubernetes Secrets for accessing the Docker Registry endpoint where On-Premise services' images reside.

    • env: environment variables.

      • 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.
      • MAPGL_TILES_API: domain name of the deployed Tiles API service.
      • MAPGL_KEYSERVER: domain name of the API Keys service.
      • MAPGL_TRAFFICSERVER: domain name of the Traffic API Proxy service. Default server is traffic-jams.2gis.com.
      • MAPGL_FLOORSSERVER: domain name of the Floors API service.
    • resources: computational resources settings for workers. See the minimal requirements table for the actual information about recommended values.

    • ingress: configuration of the Ingress resource. Adapt it to your Ingress installation. Note that to use TLS, you need to create a secret containing a certificate and a private key.

  2. Deploy the service with Helm using created values-mapgl.yaml configuration file.

    helm upgrade --install --version=1.20.2 --atomic --values ./values-mapgl.yaml mapgl-js-api 2gis-on-premise/mapgl-js-api
    
  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-floors-api.yaml
    dgctlDockerRegistry: docker.storage.example.local:5000
    
    dgctlStorage:
        host: artifacts.example.com
        bucket: onpremise-artifacts
        accessKey: AKIAIOSFODNN7EXAMPLE
        secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
        manifest: manifests/1640661259.json
        secure: false
        region: ''
        usePathStyle: true
    
    ingress:
        enabled: true
        className: nginx
        hosts:
            - host: floors.example.com
              paths:
                  - path: /
                    pathType: Prefix
        tls: []
        #- hosts:
        #  - floors.example.com
        #  secretName: secret.tls
    

    Where:

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

    • dgctlStorage: installation artifacts storage settings.

      • Fill in the common settings to access the storage: endpoint, bucket, and access credentials.
      • 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. See Installation artifacts lifecycle.
      • secure: whether to use HTTPS for interacting with the S3-compatible storage. Default value: false.
      • region: S3 storage region.
      • usePathStyle: whether to use the path-style model of accessing the S3-compatible storage. In this model, the bucket name is included into the URI path.
    • ingress: configuration of the Ingress resource. Adapt it to your Ingress installation.

  2. Deploy the service with Helm using created values-floors-api.yaml configuration file.

    helm upgrade --install --version=1.20.2 --atomic --values ./values-floors-api.yaml floors-api 2gis-on-premise/floors-api
    

    Once the Floors API service is installed, the floor plans data is imported from the installation artifacts storage to the server where docker images of the service are deployed.

Check the service in one of the following ways:

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

    http://mapgl-js-api.example.com
    
  • If you want to change the initialization settings of the map, create a test.html file with the following contents and 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-js-api.example.com/api.js"></script>
            <script>
                const map = new mapgl.Map('map', {
                    center: [55.31878, 25.23584],
                    zoom: 13,
                    useRtlTextPlugin: 'always-on', // right-to-left displaying of texts in Arabic
                });
            </script>
        </body>
    </html>
    

    In this case, the style and styleOptions options are not specified, and their default values will be resolved relative to MAPGL_HOST. If you plan to use custom styles from a separate server, the code is different:

    Code example
    <html>
        <head>
            <title>MapGL JS API. On-Premise</title>
            <style>
                #map {
                    width: 100%;
                    height: 100%;
                }
            </style>
        </head>
    
        <body>
            <div id="map"></div>
            <script src="//example.com/api.js"></script>
            <script>
                const map = new mapgl.Map('map', {
                    center: [55.31878, 25.23584],
                    zoom: 13,
                    style: '//example.com/style/', //the path to the styles folder
                    styleOptions: {
                        iconsPath: '//example.com/style/icons/', //the path to the icons folder
                        fontsPath: '//example.com/style/fonts/', //the path to the fonts folder
                        modelsPath: '//example.com/style/models/', //the path to the models folder
                    },
                    useRtlTextPlugin: 'always-on', // right-to-left displaying of texts in Arabic
                });
            </script>
        </body>
    </html>
    

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 (the example is valid for Moscow):

http://tiles-api.example.com/tiles?x=1237&y=640&z=11&v=1

A sample raster tile should be displayed.

To test the Floors API service, a building with a set of floors must be within the map view port. See an example of working with floor plans.

What's next?