CityLens | On‑Premise | Urbi Documentation
On‑Premise

Installing CityLens

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 License service
    4. Installing API Keys service
    5. Installing Urbi Pro
    6. Installing maps 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 artifacts.example.com See Fetching installation artifacts
    Kubernetes secret for accessing Docker Registry onpremise-registry-creds See Fetching installation artifacts
    Installation artifacts S3 storage domain name artifacts.example.com See Fetching installation artifacts
    Bucket name for installation artifacts onpremise-artifacts See Fetching installation artifacts
    Installation artifacts access key AKIAIOSFODNN7EXAMPLE See Fetching installation artifacts
    Installation artifacts secret key wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY See Fetching installation artifacts
    Path to the manifest file manifests/1640661259.json See Fetching installation artifacts
    License service endpoint https://license.svc See Installing License service
    MapGL JS API endpoint mapgl.example.local See Installing maps API
    Pro API endpoint https://pro-api.host See Installing Urbi Pro
  4. Make sure that the resource requirements specified in the Helm chart are met. For more information on how to do this, refer to the System requirements document.

    Note

    Contents of the Helm chart described in this chapter are relevant for the latest On-Premise version (see Release notes). To find parameters for earlier versions, open 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.

    Example:

    • Domain name for CityLens service – UI for viewing uploaded tracks: http://citylens-web.host
    • Domain name for CityLens API, where the mobile application connects and uploads tracks: http://citylens-api.host

Place a PostgreSQL cluster with the domain name citylens-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 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 citylens password 'citylens';
    
  3. Create a database owned by this user:

    create database citylens owner citylens;
    
  4. Install the PostGIS extension for PostgreSQL.

  5. Enable the PostGIS extension:

    create extension postgis;
    

Place an S3 compatible storage (for example, Ceph) with the domain name citylens-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:

    • accessKey: accessKey
    • secretAccessKey: secretAccessKey

    Remember the credentials for the user.

  2. Choose bucket names that will be used for the service. For example:

    • Bucket with main data: onprem-citylens.

Place an Apache Kafka storage with the domain name citylens-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

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-citylens.yaml
    dgctlDockerRegistry: docker.storage.example.local:5000
    
    api:
      auth:
        enabled: true
        authServerUrl: https://keycloak.host
        realm: CityLens_app
        predictorsTokens:
          camcom: token
    
      licensing:
        url: 'https://license.svc'
    
      ingress:
        className: nginx
        enabled: false
        hosts:
        - host: citylens-api.host
          paths:
          - path: /
            pathType: Prefix
        tls:
        - hosts:
          - citylens-api.host
    web:
      auth:
        enabled: true
        realm: Inspection_Portal_backend
        authServerUrl: https://keycloak.host
        clientId: citylens-web-client
        clientSecret: secret
        pkce: false
    
      ingress:
        className: nginx
        enabled: true
        hosts:
        - host: citylens-web.host
          paths:
          - path: /
            pathType: Prefix
        tls: []
        - hosts:
          - citylens-web.host
    
    worker:
      camcomSender:
        enabled: true
        apiKey: key
        endpointUrl: http://camcom-mock-service/user_upload
        sourceEnv: test
    
    kafka:
      bootstrapServer: kafka1.host:9092,kafka2.host:9092,kafka3.host:9092
      username: kafka
      password: kafka_password
      topics:
        frames: frames
        tracks: tracks
        pro: pro
        proDrivers: drivers
        logs: logs
        uploader: uploader
        framesLifecycle: flifecycle
        tracksLifecycle: tlifecycle
        predictions: predictions
      consumerGroups:
        prefix: citylens_
    
    s3:
      endpoint: https://s3.host
      accessKey: accessKey
      secretAccessKey: secretAccessKey
      bucketPrefix: citylens # an application itself will create a bucket of a bucketPrefix + %Y%m kind
      logsBucketPrefix: citylens-logs
      verifySsl: true
      setPublicReadACL: false
    
    dgctlStorage:
        host: artifacts.example.com
        secure: false
        bucket: onpremise-artifacts
        accessKey: AKIAIOSFODNN7EXAMPLE
        secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
        manifest: manifests/1640661259.json
    
    postgres:
      host: postgres.host
      port: 5432
      database: citylens
      username: citylens
      password: citylens
    
    dashboardDomain: https://citylens-web.host
    
    locale: en
    
    map:
      tileserverUrl: https://tiles-api-raster.host
      mapgl:
        host:  mapgl-js-api.host
        key: key
    
    pro:
      baseUrl: https://pro-api.host
      key: key
      verifySsl: true
      framesAssetId: ''
    
    reporters:
    - name: pro
      predictors: [camcom]
      trackTimeoutDays: 1
    
    customCAs:
      bundle: ''
      # bundle: |
      #   -----BEGIN CERTIFICATE-----
      #   ...
      #   -----END CERTIFICATE-----
      certsPath: ''
    

    Where:

    • dgctlDockerRegistry: your Docker Registry endpoint where On-Premise services' images reside.

    • api: CityLens API service settings.

      • auth: authentication settings.

        • enabled: whether the authentication is enabled.
        • authServerUrl: API URL of authentication service.
        • realm: realm for authentication.
        • predictorsTokens.camcom: randomly generated string 64 characters long (ASCII + numbers). It is passed to Camcom to access the CityLens API.
      • licensing: the License service settings.

        • url: License service URL address. Example: https://license.svc.
      • 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.

    • web: CityLens web service settings..

      • auth: authentication settings.

        • enabled: whether the authentication is enabled.
        • realm: realm for authentication.
        • authServerUrl: API URL of authentication service.
        • clientId: client ID from Keycloak.
        • clientSecret: client secret from Keycloak.
        • pkce: whether the PKCE key check is enabled.
      • 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.

    • worker: CityLens workers service settings.

      • camcomSender: CamcomSender workers settings.

        • enabled: whether Camcom Sender is enabled.
        • apiKey: access key to Camcom Sender API.
        • endpointUrl: endpoint URL for Camcom Sender.
        • sourceEnv: the environment name in Camcom provided by Camcom.
    • kafka: access settings for the Apache Kafka broker.

      • bootstrapServer: Kafka broker endpoint

      • username: username for connection.

      • password: password for connection.

      • topics: topics settings.

        • frames: list of topics for the Frames Saver worker.
        • tracks: list of topics for the Track Metadata worker.
        • pro: topic for synchronizing frames with Urbi Pro via the Reporter Pro worker.
        • proDrivers: topic for synchronizing driver tracks with Urbi Pro via the Reporter Pro worker.
        • logs: topic for mobile application logs (uploaded via CityLens API).
        • uploader: topic for the Uploader worker.
        • framesLifecycle: topic for the frames lifecycle events.
        • tracksLifecycle: topic for the tracks lifecycle events.
        • predictions: topic for prediction events from detectors.
      • consumerGroups: consumer groups settings.

        • prefix: Kafka topics prefix for the consumer groups.
    • s3: S3 compatible storage settings.

      • endpoint: S3 endpoint.
      • accessKey: S3 access key for accessing the bucket.
      • secretAccessKey: S3 secret key for accessing the bucket.
      • bucketPrefix: prefix of the bucket name in S3 for the frames buckets.
      • logsBucketPrefix: prefix of the bucket name in S3 for mobile application logs.
      • verifySsl: whether the SSL certificates validation is enabled.
      • setPublicReadACL: whether to make the S3 bucket a public one (viewing of the frames will be enabled without authorization).
    • dgctlStorage: settings of the Installation Artifacts Storage.

      • host: host address or IP of the S3 bucket.
      • secure: whether to use HTTPS for interacting with the S3 compatible storage. Default value: false.
      • bucket: name of the S3 bucket.
      • 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/1640661259.json format. This file contains the description of pieces of data that the service requires to operate. See Installation artifacts lifecycle.
    • postgres: PostgreSQL settings.

      • host: PostgreSQL read-write (rw) host address or IP.
      • port: PostgreSQL port
      • database: database name.
      • username: PostgreSQL username with rw access.
      • password: PostgreSQL username's password.
    • dashboardDomain: link to the CityLens web version.

    • locale: language used.

    • map: map settings.

      • tileserverUrl: URL of the server to obtain raster tiles.

      • mapgl: MapGL JS API access settings.

        • host: hostname of the MapGL server.
        • key: key of the MapGL server.
    • pro: group of settings responsible for integration of the CityLens with Pro.

      • baseUrl: Pro API URL for filters actualization.
      • key: Pro API authentication token
      • verifySsl: whether the SSL certificates validation is enabled.
      • framesAssetId: ID of the dataset to load frames to.
    • reporters: group of settings specifying where to upload data.

      • name: name of the reporter
      • predictors: predictor used by the reporter.
      • trackTimeoutDays: timeout (in days) to wait for track completion and obtaining frames predictions.
    • customCAs: custom certificates settings.

      • bundle: text representation of a certificate in the X.509 PEM public-key format.
      • certsPath: bundle mount directory in the container.
  2. Deploy the service with Helm using the created values-citylens.yaml configuration file:

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

Use one of the following methods:

What's next?