Urbi Pro | On-Premise | 2GIS Documentation

Installing Urbi Pro

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

Configure the cluster:

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

    • Username: ``
    • Password: ``

    Remember the credentials for the user.

  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
        bucket: onpremise-artifacts
        accessKey: AKIAIOSFODNN7EXAMPLE
        secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
        manifest: manifests/1640661259.json
        secure: false
        region: ''
        disablePayloadSigning: false
    
    s3:
        assetsDataBucket: ''
        userAssetsDataBucket: ''
        layerDataBucket: ''
        snapshotBucket: ''
        resourcesBucket: ''
    
    api:
        serviceAccount: ''
        tempPath: /tmp
        allowAnyOrigin: false
        loggingFormat: simple
    
    postgres:
        connectionString: ''
        connectionStringReadonly: ''
        password: ''
    
    keys:
        url: ''
        token: ''
    
    elastic:
        host: ''
        credentials: ''
    
    redis:
        host: ''
        port: ''
    
    catalog:
        url: ''
        key: ''
    
    navi:
        url: ''
        key: ''
    
    search:
        url: ''
    
    appAssetImporterName: asset-importer
    appUserAssetImporterName: user-asset-importer
    
    assetImporter:
        repository: 2gis-on-premise/pro-importer
        tag: 1.0.23
        schedule: 0 18 * * *
        backoffLimit: 2
        successfulJobsHistoryLimit: 3
        nodeSelector: {}
        maxParallelJobs: 4
        enabled: true
        startOnDeploy: true
    
    resources:
        requests:
            cpu: 400m
            memory: 256M
        limits:
            cpu: 1
            memory: 1024M
    
    ingress:
        enabled: true
        className: nginx
        hosts:
            - host: pro-api.example.com
              paths:
                  - path: /
                    pathType: Prefix
        tls: []
        #- hosts:
        #  - pro-api.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.
    • 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.
    • api: environment variables.

      • serviceAccount: Kubernetes service account.
      • tempPath: path to directory used for temp data.
      • allowAnyOrigin: CORS policy — allow any origin to perform requests to Pro API service.
      • loggingFormat: logging format. Possible options: default — compact JSON, renderedCompactJson — rendered JSON format, simple — just text.
    • 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.
    • 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.
    • appAssetImporterName: Data Import job name.

    • appUserAssetImporterName: User Data Import job name.

    • assetImporter: import cron job settings.

      • repository: Docker Repository Image.
      • tag: Docker image tag.
      • 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.
      • 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.
    • resources: limits for the application service. The actual information about the recommended settings values is provided in the system requirements table.

    • 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-api.yaml configuration file:

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

    • ui.resources: limits for the application service. The actual information about the recommended settings values is provided in the system requirements table.

    • ui.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.21.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: