Urbi Pro | On‑Premise | 2GIS Documentation
On‑Premise

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. Consider getting familiar with:

  2. Make sure the necessary preparation steps are completed:

    1. Preparation for installation
    2. Fetching installation artifacts
    3. Installing API Keys service
    4. Installing Traffic API Proxy
    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:

    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

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:

  1. Connect to the cluster 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 a database owned by this user:

    create database onpremise_pro owner dbuser_pro;
    

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:

  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.

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.

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
  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: []
            #- 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.

    • navi: Isochrone API settings.

    • 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.
  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
    
  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: ''
    
    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.

  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
    

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:

Install other On-Premise products: