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_VECTOR_TOKEN, TILES_RASTER_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,
   • Tilegen API,
   • Styles 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 MapGL JS API: mapgl-js-api.example.com
   • Domain name for Tiles API: tiles-api.example.com
   • Domain name for Tilegen API: tilegen-api.example.com
   • Domain name for Styles API: styles.example.com

2. Prepare infrastructure

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

Configure Redis for Tilegen API

1. Place Redis in the private network.

2. Create a user and set a password:

   Example:

   • Username: redisuser
   • Password: REDISPASSWORD-KFY87TSM0JD10LD

Configure S3 compatible storage

Configure an S3 compatible storage if you plan to install Tilegen API or Styles API. If you need to install both services, you can configure different S3 servers or use one but with different buckets.

1. Place an S3 compatible storage (e.g., Ceph) with the domain name s3.storage.example.local in the private network. It is assumed that the storage works on the standard port 80.

2. Create a user that will be used for the service:

   • Access key: ``

   • Secret key: ``

   Remember the credentials for the user.

3. Choose a bucket name that will be used for the service (for example, styles or tiles).

   This bucket must be public and have the properly configured CORS so that the files can be downloaded from a browser of any host.

Configure PostgreSQL for Styles API

Place a PostgreSQL cluster with the domain name styles-postgresql.storage.example.local in the private network. It is assumed that the cluster works on the standard port 5432.

Configure the PostgreSQL cluster for usage as a storage:

1. Connect to the cluster as a superuser (usually postgres).

2. Create a database user and set a password for the user:

   create user dbuser_styles password '';

3. Create a database owned by this user:

   create database onpremise_styles owner dbuser_styles;

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
       region: ''
       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_ONE
       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
           vector:
               token: 'TILES_VECTOR_TOKEN'
           raster:
               token: 'TILES_RASTER_TOKEN'
   
   license:
       url: 'https://license'
       retryPeriod: 30s
   
   customCAs:
       bundle: ''
       # bundle: |
       #   -----BEGIN CERTIFICATE-----
       #   ...
       #   -----END CERTIFICATE-----
       certsPath: ''
   
   # If you plan to use Tilegen API
   tilegen:
       enabled: true
       tileset:
           name: userdata
           keyspace: dgis_userdata

   Where:

   • dgctlDockerRegistry: endpoint of your Docker Registry with the images of the On-Premise services.

   • 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.
     • region: S3 storage region.
     • 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. To find out recommended resource values, see Computational resources.

     • 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 to access the Docker Registry with the images of the On-Premise services.
     • 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.vector.token: dedicated service token for getting vector data from the Tiles API service. Fetch the key by executing keysctl utility.
     • access.raster.token: dedicated service token for getting raster data from the Tiles Raster 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.

   • tilegen: settings for interacting with Tilegen API.

     • enable: whether to use Tilegen API.

     • tileset: tileset parameters.

       • name: tileset name.
       • keyspace: name of a keyspace in the database.

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

   helm upgrade --install --version=1.32.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 Tilegen 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-tilegen.yaml

   dgctlDockerRegistry: docker.storage.example.local:5000
   
   imagePullSecrets: [onpremise-registry-creds]
   
   s3:
       host: 's3.storage.example.local'
       accessKey: ''
       secretKey: ''
       vectorTilesBucket: 'tiles'
   
   redis:
       host: 'redis.example.local'
       port: 6379
   
   tilesImporter:
       hosts: 'tiles1.importer.host,tiles2.importer.host'

   Where:

   • dgctlDockerRegistry: endpoint of your Docker Registry with the images of the On-Premise services.

   • imagePullSecrets: Kubernetes Secrets to access the Docker Registry with the images of the On-Premise services.

   • s3: S3 compatible storage settings.

     • host: S3 storage endpoint.
     • accessKey: S3 access key.
     • secretKey: S3 secret key.
     • vectorTilesBucket: name of the bucket for storing vector tiles.

   • redis: Redis interaction settings.

     • host: name or IP address of the Redis host.
     • port: Redis port.

   • tilesImporter: tiles importer settings.

     • hosts: list of host names for tiles import separated by commas.

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

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

Install Styles 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-styles.yaml

   
   dgctlDockerRegistry: docker.storage.example.local:5000
   
   log:
       level: info
   
   postgres:
       host: 'styles-postgresql.storage.example.local'
       name: 'onpremise_styles'
       username: ''
       password: ''
   
   s3:
       host: 's3.storage.example.local:80'
       accessKey: ''
       secretKey: ''
       bucket: 'styles'
       publicDomain: ''
       region: ''
       secure: false
       verifySsl: false
   
   api:
       resources:
           requests:
               cpu: 50m
               memory: 128Mi
           limits:
               cpu: 1
               memory: 256Mi
   
       ingress:
           enabled: true
           className: nginx
           hosts:
               - host: styles.example.com
               paths:
                   - path: /
                       pathType: Prefix
           tls: []
           #- hosts:
           #  - styles-api.example.com
           #  secretName: secret.tls

   Where:

   • dgctlDockerRegistry: endpoint of your Docker Registry with the images of the On-Premise services.

   • log.level: logging level.

   • postgres: access settings for the PostgreSQL server.

     • host: name or IP address on the PostgreSQL host.
     • name: database name.
     • username: name of the PostgreSQL database user.
     • password: user password to connect to the PostgreSQL database.

   • s3: S3 compatible storage settings.

     • host: S3 storage endpoint.
     • accessKey: S3 access key.
     • secretKey: S3 secret key.
     • bucket: bucket name.
     • publicDomain: S3 public access domain using the HTTPS protocol.
     • region: S3 storage region.
     • secure: whether to use HTTPS for interacting with the S3 compatible storage. Default value: false.
     • verifySsl: whether to enable validation of SSL certificates. Default value: false.

   • api.resources: computational resources settings for the service. To find out recommended resource values, see Computational resources.

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

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

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

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
   
   imagePullSecrets: [onpremise-registry-creds]
   
   env:
       MAPGL_DEMO_KEY: ''
       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_STYLESERVER: https://styles.ingress.host
       MAPGL_ICONS_URL: https://s3.ingress.host/styles/assets/icons
       MAPGL_MODELS_URL: https://s3.ingress.host/styles/assets/models
       MAPGL_KEYSERVER: https://keys-api.example.com/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: endpoint of your Docker Registry with the images of the On-Premise services.

   • imagePullSecrets: Kubernetes Secrets to access the Docker Registry with the images of the On-Premise services.

   • env: environment variables.

     • MAPGL_DEMO_KEY: API key to access the service. Must be generated via the API Keys service.
     • 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_STYLESERVER: URL of the Styles API service.
     • MAPGL_ICONS_URL: URL of a style icons directory. URL must be public.
     • MAPGL_MODELS_URL: URL of a style models directory. URL must be public.
     • 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. To find out recommended resource values, see Computational resources.

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

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>

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

  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, see testing Styles API.

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.

Tilegen API

Send a GET request to the Tilegen API endpoint:

curl -X 'GET' \
  'https://tilegen-api.example.com/version' \
  -H 'accept: */*'

Service version number should be returned.

Styles API

To apply a custom style to the map, install the Platform Manager and follow the steps for uploading and applying a style.

What's next?

• Find out how to update maps API and styles.

• Install other On-Premise products:

  • search API
  • navigation API
  • Urbi Pro
  • CityLens
  • mobile SDK
  • GIS Platform
  • Platform Manager

• Learn recommendations on serving the installation:

  • backing up infrastructure databases
  • monitoring service health
  • collecting and sending logs