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

1. Consider getting familiar with:

   • Urbi Pro services documentation
   • On-Premise solution architecture
   • System requirement

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 maps API
   6. Installing search API
   7. Installing navigation API

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

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

5. 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. 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 that will be used for the service. Set a password for the user:

   create user dbuser_pro password '';

3. Create databases owned by this user:

   create database onpremise_pro owner dbuser_pro;
   create database onpremise_pro_tasks 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. It is assumed that the storage works on the standard port 80.

Configure the S3 compatible storage:

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

2. 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. It is assumed 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

1. Place an Apache Kafka storage with the domain name pro-kafka.storage.example.local in the private network. It is assumed that the storage works on the standard port 9092.

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

   • username: kafka

   • password: kafka_password

   Remember the credentials for the user.

3. (Recommended) Configure Apache Kafka topics as follows:

   Topic name	Transferred data	Recommended settings
   kafka.importTasksTopic.name	Import tasks for user datasets	Maximum message size - 5 MB (max.message.bytes: 5242880); Log retention period - 3 days (retention.ms: 259200000); Compression format - Gzip (compression.type: gzip).
   kafka.assetDataTopic.name	Objects of user datasets	Maximum message size - 5 MB (max.message.bytes: 5242880); Log retention period - 5 days (retention.ms: 432000000); Compression format - Gzip (compression.type: gzip).
   kafka.permissionsTopic.name	Messages about access rights change	Maximum message size - 5 MB (max.message.bytes: 5242880); Log retention period - 1 day (retention.ms: 86400000); Compression format - Gzip (compression.type: gzip).
   kafka.eventsTopic.name	Various events	Maximum message size - 20 MB (max.message.bytes: 20000000); Log retention period - 1 day (retention.ms: 86400000); Maximum storage size - 500 MB (retention.bytes: 524288000); Compression format - Gzip (compression.type: gzip).

   For a complete settings description, see the Apache Kafka documentation.

3. Install Urbi Pro

Install Pro API

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-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: []
           #  secretName: secret.tls
   
       pod:
           imagePullSecrets: [onpremise-registry-creds]
           resources:
               requests:
                   cpu: 400m
                   memory: 256M
               limits:
                   cpu: 1
                   memory: 1024M
       service:
           serviceAccount: ''
       settings:
           licenseKey: ''
           tempPath: /tmp
           corsOrigins: ''
           logging:
               format: simple
   
   permissions:
       settings:
           auth:
               apiKey: ''
   
   license:
       url: 'https://license.svc'
   
   s3:
       assetsDataBucket: ''
       userAssetsDataBucket: ''
       layerDataBucket: ''
       snapshotBucket: ''
       resourcesBucket: ''
   
   postgres:
       api:
           rw:
               host: 'pro-postgresql.storage.example.local'
               port: 5432
               name: 'onpremise_pro'
               username: 'dbuser_pro'
               password: ''
           ro: {}
       tasks:
           rw:
               host: 'pro-postgresql.storage.example.local'
               port: 5432
               name: 'onpremise_pro_tasks'
               username: 'dbuser_pro'
               password: ''
           ro: {}
       permissions:
           rw:
               host: 'pro-postgresql.storage.example.local'
               port: 5432
               name: 'onpremise_pro'
               username: 'dbuser_pro'
               password: ''
           ro: {}
   
   kafka:
       bootstrapServers: ''
       securityProtocol: SaslPlaintext
       createTopics: true
       sasl:
           mechanism: ScramSha512
           username: ''
           password: ''
       assetTopicsReaderGroupId: ''
       importTasksTopic:
           name: ''
           readerGroupId: ''
       assetDataTopic:
           name: ''
       eventsTopic:
           name: ''
           readerGroupId: ''
   
   keys:
       url: ''
       token: ''
   
   elastic:
       secure: false
       nodes:
           - port: 9200
             host: pro-elastic.storage.example.local
   
   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
       failedJobsHistoryLimit: 3
       nodeSelector: {}
       settings:
           maxParallelJobs: 4
       startOnDeploy: true

   Where:

   • dgctlDockerRegistry: endpoint of your Docker Registry with the images of the On-Premise services. 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.imagePullSecrets: Kubernetes Secrets to access the Docker Registry with the images of the On-Premise services.
     • 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.corsOrigins: CORS policy. If the value is empty, aany origin is allowed to perform requests to Pro API service.
     • settings.logging.format: logging format. Possible options: default - compact JSON, renderedCompactJson - rendered JSON format, simple - just text.

   • permissions.settings.auth.apiKey: access key to Permissions API access key to perform authorized actions.

   • 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: PostgreSQL settings.

     • api: read-write (postgres.api.rw) or read-only (postgres.api.ro) access settings for the onpremise_pro database.

       • host: host name or IP address.
       • port: port number.
       • name: database name.
       • username: database username.
       • password: database user password.

     • tasks: read-write (postgres.tasks.rw) or read-only (postgres.tasks.ro) access settings for the onpremise_pro_tasks database used by the microservice for managing background tasks. The set of parameters is identical to the postgres.api group but a separate database is used.

     • permissions: read-write (postgres.permissions.rw) or read-only (postgres.permissions.ro) access settings for the onpremise_pro database used by the microservice for managing user access (Permissions API). The set of parameters is identical to the postgres.api group and the same database is used.

   • kafka: Apache Kafka settings.

     • bootstrapServers: Kafka endpoints. Example: HOST1:PORT1,HOST2:PORT2.

     • securityProtocol: Kafka security protocol.

     • createTopics: whether to enable automatic creation of topics.

     • 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 user dataset import tasks.

       • name: topic name.
       • readerGroupId: ID of the Kafka consumer group for reading import tasks.

     • assetDataTopic: settings for the Kafka topic for objects in user datasets.

       • name: topic name.

     • eventsTopic: settings for the Kafka topic for 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.

     • secure: whether to use HTTPS for interacting with Elasticsearch. Default value: false.
     • nodes[0].host: Elasticsearch host address.
     • nodes[0].port: Elasticsearch port.

   • 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 jobs should be kept.
     • failedJobsHistoryLimit: how many failed jobs should be kept.
     • nodeSelector: Kubernetes node selectors.
     • settings.maxParallelJobs: how many import jobs can be run simultaneously.
     • startOnDeploy: indicates that asset import should start when service installed or updated.

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

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

Install Pro UI

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-pro-ui.yaml

   dgctlDockerRegistry: ''
   
   imagePullSecrets: [onpremise-registry-creds]
   
   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: endpoint of your Docker Registry with the images of the On-Premise services. Example: HOST:PORT.

   • imagePullSecrets: Kubernetes Secrets to access the 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.
     • 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.

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

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

curl -X 'GET' \
  'https://PRO-API/items/1,14,164' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer TOKEN' # Or see settings.auth.apiKey

For authorization, use a Bearer token or see the defined value of the settings.auth.apiKey parameter in the Pro API configuration file.

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

5. Set up user authentication

Configure an external OpenID Connect provider to authenticate end users in Urbi Pro.

What's next?

• Find out how to update Urbi Pro.

• Install other On-Premise products:

  • CityLens
  • mobile SDK
  • GIS Platform
  • Traffic API proxy
  • Platform Manager

• Learn recommendations on serving the installation:

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