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 requirements

2. Make sure the necessary preparation steps are completed:

   1. Preparation for installation
   2. Installing License service
   3. Installing API Keys service
   4. Installing maps API
   5. Installing search API
   6. 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
   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, see the System requirements document.

   Note

   Contents of Helm charts described in this chapter are relevant for the latest Urbi Pro version (see Urbi Pro releases). To find parameters for earlier versions, open the required values.yaml on GitHub and select a Pro-<version> tag 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

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

2. Connect to the cluster as a superuser (usually postgres).

3. Create a database user that will be used for the service. Set a password for the user:

   create user dbuser_pro password '';

4. Create databases owned by this user:

   create database onpremise_pro owner dbuser_pro;
   create database onpremise_pro_tasks owner dbuser_pro;

Configure S3 storage

1. Place an S3 compatible storage (e.g., Ceph or MinIO) 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.

2. Create keys to connect to the service. Save them.

   Example:

   • Access key: AKIAIOSFODNN7EXAMPLE
   • Secret key: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY

3. Choose bucket names that will be used for the service.

   Example:

   • Bucket with datasets, aggregations, and filters (assetsDataBucket): assets
   • Bucket with datasets, aggregations, and filters created by a user (userAssetsDataBucket): user_assets
   • Bucket with the prepared layer data (layerDataBucket): layer_data
   • Bucket for storing snapshots (snapshotBucket): snapshots
   • Bucket for storing static resources (resourcesBucket): resources

Configure Elasticsearch

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

2. Create a user to connect to the service. Save their credentials.

   Example:

   • Username: elasticsearch
   • Password: elasticsearch_password

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 to connect to the service. Save their credentials.

   Example:

   • Username: kafka
   • Password: kafka_password

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: true
       bucket: onpremise-artifacts
       accessKey: AKIAIOSFODNN7EXAMPLE
       secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
       manifest: manifests/pro/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: ''
   
   elastic:
       username: ''
       password : ''
       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 in the HOST:PORT format.

   • dgctlStorage: settings for access to the installation artifacts storage.

     • host: endpoint of the S3 compatible storage in the HOST:PORT format.
     • secure: whether to use HTTPS for interacting with the S3 compatible storage. Default value: false.
     • bucket: S3 bucket name.
     • accessKey: access key for accessing the S3 bucket.
     • secretKey: secret key for accessing the S3 bucket.
     • manifest: path to the manifest file in the manifests/pro/1640661259.json format. This file contains the description of pieces of data that the service requires to operate. See Installation artifacts lifecycle.
     • region: S3 compatible 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: settings for access to the S3 compatible storage.

     • assetsDataBucket: S3 bucket with system datasets, aggregations, and filters.
     • userAssetsDataBucket: S3 bucket with user-created datasets, 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 datasets 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.

   • elastic: Elasticsearch settings.

     • username: Elasticsearch username.
     • password: Elasticsearch password.
     • 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=VERSION --atomic --values ./values-pro-api.yaml pro-api 2gis-on-premise/pro-api

   In the --version parameter, specify the required Urbi Pro version. For a list of versions, see the Ubri Pro releases section.

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
     secure: true
     bucket: onpremise-artifacts
     accessKey: AKIAIOSFODNN7EXAMPLE
     secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
     manifest: manifests/pro/1640661259.json
     region: ''
     disablePayloadSigning: false
   
   ui:
     appTheme: 2gis
     appLocale: en_AE
     whiteLabel:
       configUrl: "/static/theme/pro.json"
     appInitialMapCenter: '[55.26, 25.23]'
     publicS3Url: https://artifacts.storage.example.local/
     styles:
       s3Bucket: 'pro-ui-styles'
       configUrl: 'https://artifacts.storage.example.local/pro-ui-styles/config/production/styleConfig.json'
     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
   
   stylesImporter:
     startOnDeploy: true

   Where:

   • dgctlDockerRegistry: endpoint of your Docker Registry with the images of the On-Premise services in the HOST:PORT format.

   • imagePullSecrets: Kubernetes Secrets to access the Docker Registry with the images of the On-Premise services.

   • dgctlStorage: settings for access to the installation artifacts storage.

     • host: endpoint of the S3 compatible installation artifacts storage in the HOST:PORT format.
     • secure: whether to use HTTPS for interacting with the S3 compatible storage. Default value: false.
     • bucket: S3 bucket name.
     • accessKey: access key for accessing the S3 bucket.
     • secretKey: secret key for accessing the S3 bucket.
     • manifest: path to the manifest file in the manifests/pro/1640661259.json format. This file contains the description of pieces of data that the service requires to operate. See Installation artifacts lifecycle.
     • region: S3 compatible 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: application settings.

     • appTheme: branding inside the application. Possible values:.

     • appLocale: default application language.

     • whiteLabel.configUrl: URL of the configuration file for customizing user logo, favicon, and others. Example: /static/theme/pro.json.

     • appInitialMapCenter: default map coordinates in the [lng, lat] format. Example: [55.26, 25.23] for Dubai.

     • publicS3Url: URL of the public S3 compatible storage where the styles will be stored.

     • styles.s3Bucket: S3 bucket name for styles. This bucket must be public and have the configured CORS.

     • styles.configUrl: URL of the configuration file for styles.

     • api.url: base URL for the Pro API with a trailing slash. Example: HTTP(S)://HOST/.

     • mapgl: settings for the MapGL JS API service.

       • host: host for the MapGL JS API service without protocol and trailing slash.
       • key: access key for the MapGL JS API service.
       • styleUrl: path to the directory with the styles.json configuration file for managing map styles. Example: //mapgl.ingress.host/style.
       • 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.

   • stylesImporter.startOnDeploy: whether to enable import of custom styles for Pro when installing or updating the service.

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

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

   In the --version parameter, specify the required Urbi Pro version. For a list of versions, see the Ubri Pro releases section.

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 maintaining the installation.