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

Consider getting familiar with:
Make sure the necessary preparation steps are completed:

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

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

2. Prepare infrastructure

Configure PostgreSQL

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:

Connect to the cluster as a superuser (usually postgres).
Create a database user that will be used for the service. Set a password for the user:
```
create user citylens password 'citylens';
```

Create a database owned by this user:

create database citylens owner citylens;

Install the PostGIS extension for PostgreSQL.
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. This instruction assumes that the storage works on the standard port 80.

Configure the S3-compatible storage:

Create a user that will be used for the service:
- accessKey: accessKey
- secretAccessKey: secretAccessKey
Remember the credentials for the user.
Choose bucket names that will be used for the service. For example:
- Bucket with main data: onprem-citylens.

Configure Apache Kafka

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.

3. Install CityLens

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.

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

helm upgrade --install --version=1.29.0 --atomic --values ./values-citylens.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.

What's next?

Updating CityLens