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:
- Maps service documentation
- On-Premise solution architecture
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
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 following system requirements are met (the requirements are given for the minimal amount of replicas):

For testing environment:

Service	vCPU	RAM	Storage
MapGL JS API	2	4 GB	—
Tiles API Backend	2	1 GB	Apache Cassandra
Apache Cassandra	3	48 GB	500 GB
Kubernetes Importer job	1	4 GB	—
Total amount:	8	57 GB	500 GB

For production environment:

Service	vCPU	RAM	Storage
MapGL JS API	4	4 GB	—
Tiles API Backend	8	1 GB	Apache Cassandra
Apache Cassandra	12	48 GB	500 GB
Kubernetes Importer job	4	4 GB	—
Total amount:	28	57 GB	500 GB

Note:

Detailed requirements for each service are listed in the System requirements document.

Choose domain names for the services.

Example:
- Domain name for Tiles API: tiles.example.com
- Domain name for MapGL JS API: mapgl.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).

Example:

Hosts:
- tiles-cassandra-1.storage.example.local
- tiles-cassandra-2.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
    bucket: onpremise-artifacts
    accessKey: AKIAIOSFODNN7EXAMPLE
    secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
    manifest: manifests/1640661259.json

serviceName: tiles-api-raster
type: raster

cassandra:
    hosts:
        - tiles-cassandra-1.storage.example.local
        - tiles-cassandra-2.storage.example.local
    replicaFactor: 3
    consistencyLevelRead: LOCAL_QUORUM
    consistencyLevelWrite: LOCAL_QUORUM
    credentials:
        user: cassandrauser
        password: CASSANDRAPASSWORD-DWTYB05URKZJEDDN
        jmxUser: jmxuser
        jmxPassword: JMXPASSWORD-MNZLQTFH0MDDHIX8

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

proxy:
    access:
        enabled: true
        url: http://tiles-api.example.local
        token: TILES_TOKEN
```
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.
- serviceName: name of the service:
  - for Tiles API with vector tiles support — tiles-api-webgl.
  - for Tiles API with raster tiles support — tiles-api-raster.
- type: flavor of the service.
  - for Tiles API with vector tiles support — do not specify this parameter.
  - for Tiles API with raster tiles support — raster
- cassandra: the Apache Cassandra data storage settings.
  - hosts: an array of the one of more IP adresses 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. See the Apache Cassandra documentation for details.
  - 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.
- 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.
Deploy the service with Helm using created values-tiles.yaml configuration file.

Important note:

When doing a deployment, the Kubernetes Importer job will reinitialize the Apache Cassandra keyspace in the Apache Cassandra installation specified in the values-tiles.yaml configuration.

This means that all data in this keyspace, if exists, will be completely replaced with the data from the Installation Artifacts Storage.

Existing data is preserved for a short amount of time only if you do a update, not initial deployment.
```
helm upgrade --install --version=1.4.5 --atomic --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.example.com
    MAPGL_TILES_API: tiles.example.com
    MAPGL_KEYSERVER: keys.example.com
    MAPGL_TRAFFICSERVER: traffic-proxy.example.com

resources:
    requests:
        cpu: 30m
        memory: 32M
    limits:
        cpu: 100m
        memory: 64M

ingress:
    hosts:
        - host: mapgl.example.com
    tls:
        - hosts:
              - mapgl.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.
- 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.4.5 --atomic --values ./values-mapgl.yaml mapgl-js-api 2gis-on-premise/mapgl-js-api

4. Test deployment

Test MapGL JS API service

To test the operability of the MapGL JS API service and Tiles API service for vector tiles, do one of the following:

Open the domain name or IP address of the service in your browser:
```
http://mapgl.example.com
```

Write a code for displaying the sample map, then 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.example.com/api.js"></script>
        <script>
            const map = new mapgl.Map('map', {
                center: [55.31878, 25.23584],
                zoom: 13,
                style: '//mapgl.example.com/style/',
                styleOptions: {
                    iconsPath: '//mapgl.example.com/style/images/',
                    fontsPath: '//mapgl.example.com/style/fonts/',
                },
                useRtlTextPlugin: 'always-on',
                zoom: 13,
            });
        </script>
    </body>
</html>

Note:

This code slightly differs from the code placed in MapGL JS API documentation. If you use the code examples from the documentation, do not forget to adapt them to your On-Premise Maps service deployment, as shown above.

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

Test 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.example.com/tiles?x=1237&y=640&z=11&v=1

A sample raster tile should be displayed.

What's next?

Find out how to update the service:
- Updating maps API
Install other On-Premise products: