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. Before installing

1. Consider getting familiar with:

   • Maps service documentation
   • On-Premise solution architecture

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	HTTP(S)://HOST	See Installing License service
   API Keys service endpoint	keys.example.local	See Installing API Keys service
   Traffic API Proxy endpoint	traffic-proxy.example.local	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:

   • MapGL JS API,
   • Tiles API,
   • Floors API.

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

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-api.example.com

2. Prepare infrastructure required for the service

Configure Apache Cassandra

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

3. Install Maps services

Install Tiles API service

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/2gis-on-premise
   
   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
           caCrt: ''
   
   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:
           hosts:
               - host: tiles-api.example.com
   
   proxy:
       access:
           enabled: true
           url: http://keys.example.local
           token: TILES_TOKEN
   
   license:
       url: ''
       retryPeriod: 30s
   

   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).
       • caCrt: Apache Cassandra CA certificate.

   • 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: HTTP(S)://HOST.
     • retryPeriod: how often Tiles API should try to update license status if it is failing to get it.

3. Deploy the service with Helm using created values-tiles.yaml configuration file.

   helm upgrade --install --version=1.10.0 --atomic --wait --timeout 7200 --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.

Install MapGL JS API 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/2gis-on-premise
   
   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-api.example.com
   
   resources:
       requests:
           cpu: 30m
           memory: 32M
       limits:
           cpu: 100m
           memory: 64M
   
   ingress:
       hosts:
           - host: mapgl-js-api.example.com
       tls:
           - hosts:
                 - mapgl-js-api.example.com
             secretName: mapgl-js-api
   

   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.10.0 --atomic --values ./values-mapgl.yaml mapgl-js-api 2gis-on-premise/mapgl-js-api
   

Install Floors API service (optional)

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/2gis-on-premise
   
   dgctlStorage:
       host: artifacts.example.com
       bucket: onpremise-artifacts
       accessKey: AKIAIOSFODNN7EXAMPLE
       secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
       manifest: manifests/1640661259.json
   
   ingress:
       hosts:
           - host: floors-api.example.com
   

   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.

   • 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.10.0 --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.

4. Test deployment

MapGL JS API service

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.

Tiles API service with raster tiles support

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.

Floors API service

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?

• Find out how to update the service:

  • Updating maps API

• Install other On-Premise products:

  • Search API
  • Navigation API
  • GIS Platform
  • Traffic API Proxy