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

Make sure that the resource requirements specified in the Helm charts are met:
- MapGL JS API,
- Tiles API,
- Styles 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.
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 Styles API: styles.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

Configure PostgreSQL for Styles API

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

Configure the PostgreSQL cluster for usage as a storage:

Connect to the cluster a superuser (usually postgres).
Create a database user that will be used for the service. Set a password for the user:
```
create user dbuser_styles password '';
```

Create a database owned by this user:

create database onpremise_styles owner dbuser_styles;

Configure S3 storage for Styles API

Place an S3 compatible storage (e.g., Ceph) with the domain name styles-s3.storage.example.local in the private network. This instruction assumes that the storage works on the standard port 80.

Configure the S3 compatible storage:

Create a user that will be used for the service. Remember the credentials for the user:
- Access key: ``
- Secret key: ``
Remember the credentials for the user.
Choose a bucket name that will be used for the service (for example, styles).

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

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

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_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.
  - 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 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.
Deploy the service with Helm using created values-tiles.yaml configuration file.
```
helm upgrade --install --version=1.31.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 Styles 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-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: 'styles-s3.storage.example.local:80'
    accessKey: ''
    secretKey: ''
    bucket: 'styles'
    publicDomain: ''

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: your Docker Registry endpoint where On-Premise services' images reside.
- 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 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.
- 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.

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

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

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

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_ICONS_URL: https://s3.ingress.host/styles/assets/icons
    MAPGL_MODELS_URL: https://s3.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 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.

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

helm upgrade --install --version=1.31.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

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

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.
  - 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.
- 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.
Deploy the service with Helm using created values-floors-api.yaml configuration file.
```
helm upgrade --install --version=1.31.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>

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.

Styles API

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

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 and styles:
- Updating maps API
Install other On-Premise products: