Installing Urbi Pro

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
S3 compatible Installation Artifacts Storage endpoint	`artifacts.storage.local`	See Fetching installation artifacts
Installation Artifacts Storage bucket name	`onpremise-artifacts`	See Fetching installation artifacts
Installation Artifacts Storage access key	`AKIAIOSFODNN7EXAMPLE`	See Fetching installation artifacts
Installation Artifacts Storage secret key	`wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY`	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
MapGL JS API endpoint	`http://mapgl-js-api`	See Installing maps API
Catalog APIs endpoint	`http://catalog-api`	See Installing search API
Navigation API endpoint	`http://navi-front`	See Installing navigation API
API Keys	`MAPGL_KEY` `CATALOG_KEY` `NAVI_KEY`	See Installing API Keys service

Make sure that the resource requirements specified in the Helm charts are met:
- Pro API,
- Pro UI.
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 Urbi Pro services. For example:
- Domain name for the API backend: pro-api.example.com
- Domain name for the frontend: pro-ui.example.com

2. Prepare infrastructure

Configure PostgreSQL

Place a PostgreSQL cluster with the domain name pro-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_pro password '';
```

Create a database owned by this user:

create database onpremise_pro owner dbuser_pro;

Configure S3 storage

Place an S3 compatible storage (e.g., Ceph) with the domain name pro-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 bucket names that will be used for the service. For example:
- Bucket with common datasets, aggregations, and filters: assets.
- Bucket with prepared layer data: layer_data.
- Bucket with user-created datasets, aggregations, and filters: user_assets.

Configure Elasticsearch

Place an Elasticsearch cluster with the domain name pro-elastic.storage.example.local in the private network. This instruction assumes that the cluster works on the standard port 9200.

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

Username: ``
Password: ``

Remember the credentials for the user.

Configure Apache Kafka

Place an Apache Kafka storage with the domain name pro-kafka.storage.example.local in the private network. This instruction assumes that the storage works on the standard port 9092.

Create a user that will be used for the service:

username: kafka
password: kafka_password

3. Install Urbi Pro

Install Pro API

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-pro-api.yaml
```
dgctlDockerRegistry: ''

dgctlStorage:
    host: artifacts.storage.example.local:443
    secure: false
    bucket: onpremise-artifacts
    accessKey: AKIAIOSFODNN7EXAMPLE
    secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
    manifest: manifests/1640661259.json
    region: ''
    disablePayloadSigning: false

api:
    ingress:
        enabled: true
        className: nginx
        hosts:
            - host: pro-api.example.com
              paths:
                  - path: /
                    pathType: Prefix
        tls: []
        #- hosts:
        #  - pro-api.example.com
        #  secretName: secret.tls
    pod:
        resources:
            requests:
                cpu: 400m
                memory: 256M
            limits:
                cpu: 1
                memory: 1024M
    service:
        serviceAccount: ''
    settings:
        licenseKey: ''
        tempPath: /tmp
        allowAnyOrigin: false
        logging:
            format: simple

license:
    url: 'https://license.svc'

s3:
    assetsDataBucket: ''
    userAssetsDataBucket: ''
    layerDataBucket: ''
    snapshotBucket: ''
    resourcesBucket: ''

postgres:
    connectionString: ''
    connectionStringReadonly: ''
    password: ''

kafka:
    bootstrapServers: ''
    securityProtocol: SaslPlaintext
    sasl:
        mechanism: ScramSha512
        username: ''
        password: ''
    assetTopicsReaderGroupId: ''
    importTasksTopic:
        name: ''
        readerGroupId: ''
    assetDataTopic:
        name: ''
    eventsTopic:
        name: ''
        readerGroupId: ''

keys:
    url: ''
    token: ''

elastic:
    host: ''
    credentials: ''

redis:
    host: ''
    port: ''

catalog:
    url: ''
    key: ''

navi:
    url: ''
    key: ''

search:
    url: ''

assetImporter:
    appName: asset-importer
    repository: 2gis-on-premise/pro-importer
    schedule: 0 18 * * *
    backoffLimit: 2
    successfulJobsHistoryLimit: 3
    nodeSelector: {}
    settings:
        maxParallelJobs: 4
    enabled: true
    startOnDeploy: true
```
Where:
- dgctlDockerRegistry: your Docker Registry endpoint where On-Premise services' images reside. Example: HOST:PORT.
- 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: 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.
  - region: S3 storage region.
  - disablePayloadSigning: whether to disable payload signing. If the S3 storage does not support the AWS Signature Version 4 streaming, the value must be true. Default value: false.
- api: environment variables.
  - 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.
  - pod.resources: computational resources settings for the service. To find out recommended resource values, see Computational resources.
  - service.serviceAccount: Kubernetes service account.
  - settings.licenseKey: On-Premise license key.
  - settings.tempPath: path to directory used for temp data.
  - settings.allowAnyOrigin: CORS policy — allow any origin to perform requests to Pro API service.
  - settings.logging.format: logging format. Possible options: default — compact JSON, renderedCompactJson — rendered JSON format, simple — just text.
- license.url: License service URL.
- s3: S3 storage settings.
  - assetsDataBucket: S3 bucket with system datasets, aggregations, and filters.
  - userAssetsDataBucket: S3 bucket with user-created assets, aggregations, and filters.
  - layerDataBucket: S3 bucket with prepared layer data.
  - snapshotBucket: S3 bucket for storing snapshots of incremental data updates.
  - resourcesBucket: S3 bucket for storing static resources.
- postgres: access settings for the PostgreSQL server.
  - connectionString: connection string to the PostgreSQL database — Server=SERVER_URL;Database=DB_NAME;UID=USER_NAME;.
  - connectionStringReadonly: connection string to the readonly node of PostgreSQL database — Server=SERVER_URL;Database=DB_NAME;UID=USER_NAME;.
  - password: user password to connect to the PostgreSQL database.
- kafka: Apache Kafka settings.
  - bootstrapServers: Kafka endpoints. Example: HOST1:PORT1,HOST2:PORT2.
  - securityProtocol: Kafka security protocol.
  - sasl: SASL settings.
    - mechanism: SASL mechanism.
    - username: SASL username.
    - password: SASL user password.
  - assetTopicsReaderGroupId: ID of the Kafka consumer group for reading streaming assets data.
  - importTasksTopic: settings for the Kafka topic for running import tasks.
    - name: topic name.
    - readerGroupId: ID of the Kafka consumer group for reading import tasks.
  - assetDataTopic: settings for the Kafka topic for managing asset data updates.
    - name: topic name.
  - eventsTopic: settings for the Kafka topic for managing events.
    - name: topic name.
    - readerGroupId: ID of the Kafka consumer group for reading events.
- keys: key management service access settings.
  - url: API URL of keys.api service for managing partners' keys to 2GIS services. Example: HTTP(S)://HOST.
  - token: keys.api access token.
- elastic: Elasticsearch settings.
  - host: Elasticsearch host address. Example: HTTP(S)://HOST:PORT.
  - credentials: username and password to connect to the Elasticsearch — USER_NAME:PASSWORD.
- redis: Redis settings.
  - host: Redis host address. Example: HTTP(S)://HOST.
  - port: Redis port.
- catalog: Catalog APIs settings.
  - url: URL for Catalog APIs. Example: HTTP(S)://HOST.
  - key: access key to Catalog APIs.
- navi: Isochrone API settings.
  - url: URL for Isochrone API. Example: HTTP(S)://HOST.
  - key: access key to Isochrone API.
- search: Search API settings.
  - url: URL for Search API. Example: HTTP(S)://HOST.
- assetImporter: import cron job settings.
  - appName: Data Import job name.
  - repository: Docker Repository Image.
  - schedule: import job schedule in cron-format. Example: */10 * * * *.
  - backoffLimit: the number of retries before considering a Job as failed.
  - successfulJobsHistoryLimit: how many completed and failed jobs should be kept.
  - nodeSelector: Kubernetes node selectors.
  - settings.maxParallelJobs: how many import jobs can be run simultaneously.
  - enabled: if assetImporter is enabled for the service.
  - startOnDeploy: indicates that asset import should start when service installed or updated.

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

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

Install Pro UI

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-pro-ui.yaml
```
dgctlDockerRegistry: ''

dgctlStorage:
    host: artifacts.storage.example.local:443
    bucket: onpremise-artifacts
    accessKey: AKIAIOSFODNN7EXAMPLE
    secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
    manifest: manifests/1640661259.json
    secure: false
    region: ''
    disablePayloadSigning: false

ui:
    appLocale: en_AE

    appInitialMapCenter: '[37.64, 55.74]'

    api:
        url: 'https://pro-api.example.com/'

    mapgl:
        host: 'mapgl-js-api.example.com'
        key: ''
        styleUrl: ''
        stylePreview: ''

resources:
    requests:
        cpu: 300m
        memory: 256Mi
    limits:
        cpu: 1
        memory: 384Mi

ingress:
    enabled: true
    className: nginx
    hosts:
        - host: pro-ui.example.com
            paths:
                - path: /
                pathType: Prefix
    tls: []
    #- hosts:
    #  - pro-ui.example.com
    #  secretName: secret.tls
```
Where:
- dgctlDockerRegistry: your Docker Registry endpoint where On-Premise services' images reside. Example: HOST:PORT.
- 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.
  - disablePayloadSigning: whether to disable payload signing. If the S3 storage does not support the AWS Signature Version 4 streaming, the value must be true. Default value: false.
- ui.appLocale: language in the app. Possible values: en_AE, ru_RU.
- ui.appInitialMapCenter: default map coordinates, it contains of two numbers in an array: [lng, lat]. Example: [55.27, 25.2] for Dubai, [37.64, 55.74] for Moscow.
- ui.api.url: base URL for the API. Example: HTTP(S)://HOST/.
- ui.mapgl.host: host for the MapGL JS API service without protocol and trailing slash. Example: HOST.
- ui.mapgl.key: key for the MapGL JS API service.
- ui.mapgl.styleUrl: path to the directory with the styles.json configuration file for managing map styles. Example: //mapgl.ingress.host/style.
- ui.mapgl.stylePreview: URL for a thumbnail image that will be displayed as the default style preview in the map styles manager.
- resources: computational resources settings for the service. To find out recommended resource values, see Computational resources.
- 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-pro-ui.yaml configuration file:

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

4. Test deployment

Send the following request using cURL or similar tool:

https://pro-api.example.local/building/items?bounds=POLYGON%20%28%2854.605596%2024.429549%2C%2054.539606%2024.429549%2C%2054.539606%2024.413378%2C%2054.605596%2024.413378%2C%2054.605596%2024.429549%29%29

The response should return a HTTP 200 status code and a list of elements in JSON format.

What's next?

Find out how to update the service:

Updating Urbi Pro

Install other On-Premise products: