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 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
   7. 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/citylens/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 charts are met:

   • CityLens API and CityLens Routes API
   • CityLens Routes UI

   For more information on how to do this, see the System requirements document.

   Note

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

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

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

3. Create a database user and set a password for them:

   create user citylens password 'wNgJamrIym8UAcdX';

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

5. Install the PostGIS extension for PostgreSQL.

6. Enable the PostGIS extension:

   create extension postgis;

Configure S3 storage

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

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

   Example:

   • Access key: PHEI4AHTHEETHAHXEEGE
   • Secret key: aiw6ahlaeshahngaiJaebie6aeth0aiV2pucuey1

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

   Example:

   • Username: kafka
   • Password: kafka_password

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: PHEI4AHTHEETHAHXEEGE
     secretAccessKey: aiw6ahlaeshahngaiJaebie6aeth0aiV2pucuey1
     bucketPrefix: onprem-citylens # an application 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/citylens/1640661259.json
   
   postgres:
     host: postgres.host
     port: 5432
     database: citylens
     username: citylens
     password: citylens
   
   routes:
     imagePullSecrets: [onpremise-registry-creds]
     adminCredentials:
        username: admin
        password: secret_password
     endpointInternalApiKey:
        dataScience: 451d6159-191a-4391-bf1e-c36224a859d2randomKey
        companies: fc3b5fa0-aa2a-488a-9fa6-bf6fe3f42b6frandomKey
     worker:
       busConfig:
         consumers:
           appEvents:
             groupId: ''
     postgres:
       api:
         database: routes
       hangfire:
         database: hangfire
       realtimeDataApi:
         database: realtime_data
     navi:
       url: http://navi-front
       key: key
     pro:
       authorizationToken: ''
     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 in the HOST:PORT format.

   • 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: settings for access to the S3 compatible storage.

     • endpoint: endpoint of the S3 compatible storage in the HOST:PORT format.
     • accessKey: access key for accessing the S3 bucket.
     • secretAccessKey: secret key for accessing the S3 bucket.
     • bucketPrefix: prefix of the S3 bucket name for the frames buckets.
     • logsBucketPrefix: prefix of the S3 bucket name for mobile application logs.
     • verifySsl: whether to enable the SSL certificates validation when connecting to s3.endpoint.
     • setPublicReadACL: whether to make the S3 bucket a public one (viewing of the frames will be enabled without authorization).

   • 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/citylens/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.
     • adminCredentials: access settings for Hangfire (Task Scheduler).
       • username: username. Required parameter.
       • password: password. Required parameter.
     • endpointInternalApiKey: keys for accessing internal services without authorization.
       • dataScience: access key for the Data Science controller. The key must be unique and consist of letters and numbers. Required parameter.
       • companies: access key for the companies controller. The key must be unique and consist of letters and numbers. Required parameter.
     • worker.busConfig.consumers.appEvents.groupId: ID of the Kafka consumer group for events.
     • postgres: PostgreSQL access settings.
       • api.database: name of the database that the API can access.
       • hangfire.database: name of the database that the hangfire can access (for the Task Planner).
       • realtimeDataApi.database: name of the database that the RealtimeData API can access (for getting the current driver geolocation).
     • 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.
     • 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 to enable the SSL certificates validation.
     • 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=VERSION --atomic --values ./values-citylens-api.yaml citylens 2gis-on-premise/citylens

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

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_DEFAULT_CENTER: ''
       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 in the HOST:PORT format.

   • 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_DEFAULT_CENTER: coordinates of the default map center in longitude,latitude format (for example, 55.26553,25.23399).
     • 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=VERSION --atomic --values ./values-citylens-ui.yaml citylens 2gis-on-premise/citylens

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

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