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
-
Consider getting familiar with:
-
Make sure the necessary preparation steps are completed:
-
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 -
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.
-
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
- Domain name for Tiles API:
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
-
Select which variant of Tiles API you want to install: for vector or raster tiles.
-
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 themanifests/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. Theuser
andpassword
values are necessary, whilejmxUser
andjmxPassword
are only used for clearing snapshots (see Updating Tiles API service). Default value for each setting iscassandra
.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
) andwriterNum
(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
andclearSnapshots
: 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 theapi.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 executingkeysctl
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.
-
-
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
-
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 istraffic-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.
-
-
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)
-
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 themanifests/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.
-
-
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:
-
Install other On-Premise products: