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	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:

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

   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

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
   
   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:
       environment: ''
       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.

     • environment: environment name, not more than 7 symbols.
     • 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.27.0 --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.

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
   
   env:
       MAPGL_HOST: https://mapgl-api.ingress.host
       MAPGL_TILES_API: https://tiles-api.ingress.host
       MAPGL_TILESET: web
       MAPGL_IMMERSIVE_TILESET: web_immersive
       MAPGL_TRAFFICSERVER: https://traffic-proxy.ingress.host
       MAPGL_FLOORSSERVER: https://floors-api.ingress.host
       MAPGL_STYLESERVER: https://styles.ingress.host
       MAPGL_ICONSPATH: https://styles.ingress.host/styles/assets/icons
       MAPGL_MODELSPATH: https://styles.ingress.host/styles/assets/models
       MAPGL_KEYSERVER: https://keys-api.ingress.host/public/v1/keys/{keyID}/services/mapgl-js-api
       MAPGL_RTLPLUGIN: https://mapgl-api.ingress.host/api/js/plugins/rtl-v1.0.0.js
       MAPGL_RTLPLUGINHASH:
       MAPGL_INVALID_KEY_MESSAGE: Your MapGL key is invalid.
   
   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: URL of the service, which your applications use to communicate with the On-Premise Maps service.
     • MAPGL_TILES_API: URL of the Tiles API service.
     • MAPGL_TILESET: tileset of the Tiles API service with vector tiles.
     • MAPGL_IMMERSIVE_TILESET: tileset of the Tiles API service with immersive data tiles (e.g., 3D models).
     • MAPGL_TRAFFICSERVER: URL of the Traffic API Proxy service.
     • MAPGL_FLOORSSERVER: URL of the Floors API service.
     • MAPGL_STYLESERVER: URL of the styles API.
     • MAPGL_ICONSPATH: URL of a style icons directory.
     • MAPGL_MODELSPATH: URL of a style models directory.
     • MAPGL_KEYSERVER: URL of the API Keys service.
     • MAPGL_RTLPLUGIN: URL of the plugin for right-to-left (RTL) languages support.
     • MAPGL_RTLPLUGINHASH: SHA512 hash of the RTL plugin.
     • MAPGL_INVALID_KEY_MESSAGE: error message text for invalid MapGL JS API key.

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

5. Add map style

You can create a unique map style and use it in your environment. Follow the steps below:

1. Install the Platform Manager to use it for uploading styles later.

2. Open the styles editor and create your map style.

   See instructions on creating and configuring styles in the editor documentation.

3. Export the created style:

   1. In the top menu of the style editor, select Share and then click Export the style.

   2. Select the required style from the list and click Export.

      Generation of an exportable archive starts in a new tab.

   3. When the style is in the Done status, select it from the list again and click Download the style.

   4. Save the generated .tar.gz archive locally.

4. Upload the style to your On-Premise environment:

   1. Open the Platform Manager in a browser.
   2. Go to the Map Styles tab and click Upload Style.
   3. Add the exported .tar.gz archive and wait until it is uploaded.

5. Check how the style looks in a sandbox: go to the Map Styles tab and click the required style name.

6. Copy the generated style ID and apply it to the map using MapGL JS API.

You can upload different versions of one style and switch them in the Platform Manager. For details, see the instruction on updating styles.

What's next?

• Find out how to update the service and styles:

  • Updating maps API

• Install other On-Premise products:

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