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

1. Consider getting familiar with:

   • CityLens 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
   8. Installing Urbi Pro

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
   Catalog APIs endpoint	catalog-api.example.local	See Installing search 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
   • Domain name for CityLens Routes API (backend service for planning tasks and building routes): http://citylens-routes-api.host

2. Prepare infrastructure

Configure PostgreSQL

Place a PostgreSQL cluster with the domain name citylens-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 and set a password for the user:

   create user citylens password 'citylens';

3. Create databases owned by this user:

   create database citylens owner citylens;
   create database routes owner citylens;
   create database hangfire owner citylens;
   create database realtime_data owner citylens;

4. Install the PostGIS extension for PostgreSQL.

5. Enable the PostGIS extension:

   create extension postgis;

Configure S3 storage

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

   • accessKey: accessKey

   • secretAccessKey: secretAccessKey

   Remember the credentials for the user.

2. Choose prefixes for bucket names: a prefix for frames and a prefix for mobile application logs (bucketPrefix and logsBucketPrefix respectively in the Helm chart). Buckets will be generated in runtime.

   Example:

   • Bucket with main data: onprem-citylens.

Configure Apache Kafka

1. Place an Apache Kafka storage with the domain name citylens-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	Transmitted data	Recommended settings
kafka.topics.frames	Frames from the mobile application	Maximum message size - 10 MB (max.message.bytes: 10485760); Log file retention period - 2 days (retention.ms: 172800000).
kafka.topics.tracks	Track metadata and GPS track	Maximum message size - 1 MB (max.message.bytes: 1048576); Log file retention period - 2 days (retention.ms: 172800000).
kafka.topics.logs	Track logs from the mobile application	Maximum message size - 5 MB (max.message.bytes: 5242880); Log file retention period - 2 days (retention.ms: 172800000); Compression format - Gzip (compression.type: gzip).
kafka.topics.predictions	Detections	Maximum message size - 1 MB (max.message.bytes: 1048576)
kafka.topics.framesLifecycle	Frame data	Maximum message size - 1 MB (max.message.bytes: 1048576)
kafka.topics.tracksLifecycle	Track data	Maximum message size - 1 MB (max.message.bytes: 1048576)
kafka.topics.objectsLifecycle	Recognized object data	Maximum message size - 1 MB (max.message.bytes: 1048576)
kafka.topics.pro	Frames dataset	Maximum message size - 1 MB (max.message.bytes: 1048576)
kafka.topics.proDrivers	Drivers dataset	Maximum message size - 5 MB (max.message.bytes: 5242880)
kafka.topics.proObjects	Objects dataset	Maximum message size - 1 MB (max.message.bytes: 1048576)

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

3. Install CityLens

Install CityLens API and CityLens Routes API

1. Create a Helm configuration file (one file is required for installing both CityLens API and CityLens Routes API). See here for more details on the available settings.

   The example is prefilled with the necessary data collected on previous steps.

   values-citylens-api.yaml

   dgctlDockerRegistry: docker.storage.example.local:5000
   
   api:
     auth:
       enabled: true
       authServerUrl: https://keycloak.host
       realm: CityLens_app
       storeOIDCUserinfoFields: []
       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
     reporterPro:
       enabled: true
       predictors: [camcom]
       replicas: 1
   
   kafka:
     bootstrapServer: kafka1.host:9092,kafka2.host:9092,kafka3.host:9092
     username: kafka
     password: kafka_password
     topics:
       frames: frames
       tracks: tracks
       pro: pro
       proObjects: objects
       proDrivers: drivers
       logs: logs
       uploader: uploader
       framesLifecycle: flifecycle
       tracksLifecycle: tlifecycle
       objectsLifecycle: olifecycle
       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
   
   routes:
     imagePullSecrets: [onpremise-registry-creds]
     worker:
       busConfig:
         consumers:
           appEvents:
             groupId: ''
     postgres:
       database: routes
     hangfire:
       postgres:
         database: hangfire
     navi:
       url: http://navi-front
       key: key
     pro:
       authorizationToken: ''
     realtimeDataApi:
       postgres:
         database: realtime_data
     realtimeData:
       url: https://realtimedata-api.host
   
   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: ''
     objectsAssetId: ''
   
   customCAs:
     bundle: ''
     # bundle: |
     #   -----BEGIN CERTIFICATE-----
     #   ...
     #   -----END CERTIFICATE-----
     certsPath: ''

   Where:

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

   • api: CityLens API service settings.

     • auth: authentication settings.

       • enabled: whether the authentication is enabled.
       • authServerUrl: API URL of authentication service.
       • realm: realm for authentication.
       • storeOIDCUserinfoFields: list of fields from the OIDC provider response for storing information about drivers that upload tracks.
       • 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: ID of the OpenID Connect provider client.
       • clientSecret: secret of the OpenID Connect provider client.
       • 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.

     • reporterPro: settings for uploading data to Urbi Pro.

       • enabled: whether integration with Urbi Pro is enabled.
       • predictors: predictor used by the reporter.
       • replicas: number of pod replicas.

   • 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.
       • proObjects: topic for synchronizing localized detections (detected objects) 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.
       • objectsLifecycle: topic for the objects 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.

   • routes: CityLens Routes API settings.

     • imagePullSecrets: Kubernetes Secrets to access the Docker Registry with the images of the On-Premise services.
     • worker.busConfig.consumers.appEvents.groupId: ID of the Kafka consumer group for events.
     • postgres.database: PostgreSQL database name.
     • hangfire.postgres.database: PostgreSQL database name that hangfire can access to.
     • navi: settings for integration with navigation APIs.
       • url: URL to access Navi-Front.
       • key: key to access navigation APIs. Make sure that the following conditions are met:
         • This key contains access rights for Routes Planner API.
         • A corresponding service token from the API keys service is added to the Navi-Router configuration file (keys.apis.route-planner-api parameter).
     • pro: settings for integration with Urbi Pro.
       • authorizationToken: Bearer token for sending data to Urbi Pro. For details, see the uploading data via API instruction.
     • realtimeDataApi.postgres.database: PostgreSQL database name that RealtimeData API (for getting the current driver geolocation) can access to.
     • realtimeData: settings for integration with RealtimeData API.
       • url: URL to access RealtimeData API.

   • 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: host name 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.
     • objectsAssetId: ID of the dataset to load objects to.

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

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

Install CityLens Routes 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-citylens-ui.yaml

   dgctlDockerRegistry: docker.storage.example.local:5000
   
   imagePullSecrets: [onpremise-registry-creds]
   
   env:
       CATALOG_API_URL: 'https://catalog-api.ingress.host'
       MAPGL_API_URL: 'http://mapgl-js-api.ingress.host'
       MAPGL_KEY: ''
       SSO_API_URL: ''
       SSO_CLIENT_ID: ''
       SSO_CLIENT_SECRET: ''
       SSO_SCOPE: 'openid email name phone'
       ROUTES_API_URL: 'http://citylens-routes-api.ingress.host'

   Where:

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

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

   • env: environment settings.

     • CATALOG_API_URL: base URL for Catalog APIs.
     • MAPGL_API_URL: base URL for MapGL JS API.
     • MAPGL_KEY: access key for MapGL JS API.
     • SSO_API_URL: base API URL for Single Sign-On (SSO) authorization in the <origin>/realms/<realm> format (for example, https://<domain>.com/realms/Inspection_Portal_backend).
     • SSO_CLIENT_ID: OpenID client identifier for SSO authorization.
     • SSO_CLIENT_SECRET: OpenID client secret for SSO authorization.
     • SSO_SCOPE: set of user attributes requested by the OpenID client for SSO authorization.
     • ROUTES_API_URL: base URL for CityLens Routes API.

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

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

4. Test deployment

Use one of the following methods:

• Go to http://citylens-web.host.
• Launch the CityLens mobile app.

5. Set up user authentication

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

What's next?

• Find out how to update CityLens.

• Install other On-Premise products:

  • mobile SDK
  • GIS Platform
  • Platform Manager

• Learn recommendations on serving the installation:

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