Installation instructions

Deployment preparation

Downloading

Download and unpack the BAF distribution kit onto the machine where you plan to install it. To do this, use the command below:

$ curl --output baf.zip distribution link

In the curl request, specify a link to the BAF distribution kit (zip file). A link to the folder that contains the distribution kit and pdf documentation will be sent to you in the email.

Next, move the license file face_sdk.lic (the file is attached to the email) to the setup folder.

note

Ensure the license file is named face_sdk.lic. Using any other name will result in errors during secrets generation.

Contents of the distribution kit:

• ./cli.sh: entry point to run the commands
• ./cfg: folder with configuration files

Further commands are to be executed in the system console from setup directory.

Uploading of images

First, upload the product images from the archive to the local registry:

$ ./cli.sh generic load-images

Then, upload the infrastructure images from the archive to the local registry:

$ ./cli.sh smc load-images

Configuration

Basic configuration

Enter environment variables

Open the configuration files below in a text editor, set values for the variables and save changes.

note

In YAML files, values specified with a dot indicate nesting. :::

Configuration File	Variables
./cfg/smc.settings.cfg	apiserver_advertise_address: address of the kube-apiserver. In most cases this is the machine's internal IP address. external_ip_address: address for the ingress-controller. Here you need to specify the machine's external IP address.
./cfg/license-server.settings.cfg	license_key: this key is usually sent in the accompanying email to the distribution kit. To get the key, contact your sales manager. This key is not required for the trial period. license_server_address: address of the license server.
./cfg/platform.secrets.json	license-secret: here you need to set a license key and address of the license server instead of license_server_address. docker-registry: values you need to specify if external docker-registry is used. rabbit-secret : user name and password to get access to a message broker, used for internal interaction of OMNI Platform services. Set an arbitrary name that consists of Latin letters without spaces and a password that consists of Latin letters and numbers without spaces. postgres-root-credentials: username and password for the database's root user. This admin user serves as the system's administrator, while the default user is intended for non-privileged access. platform-service-key: secret key required for internal communication between OMNI Platform services. platform-user-secret : user credentials (email address and password) used for access to OMNI Platform. Users will be created automatically on the first deployment. The specified email address must include numbers, Latin letters and symbols. This admin user serves as the system's administrator, while the default user is intended for non-privileged access. platform-email-secret: SMTP server settings. To disable sending emails, leave these fields blank. minio-credentials: username and password for root user in object storage storage-engine-postgres: username, password and database name for the platform. event-service-postgres: username, password and database name for the event-service.
./cfg/platform.values.yaml	backend.query_limit: this value limits the number of returned elements in API requests to get system objects. Increasing this limit is not recommended, as API request runtime may increase several times. Also, please note that increasing the limits will lead to the system degradation. backend.index_update_period: this value in seconds describing the amount of time the added profile will appear in the search index. The default value is 60 seconds. To speed up the index updating, decrease the parameter value. backend.enable_profile_autogeneration: auto-generation of profiles for incoming activities from the agent. Please note that enabling this option will increase the consumption of license resources (database size). To enable this function, set the value to 1. ingress.rules.gateway.host: domain name or IP address used in ingress to route requests to Kubernetes services postgres.enable: disable if using your own database server. You need to change the values for postgres-root-credentials in the ./cfg/platform.secrets.json file and the values for postgres.host and postgres.port in the current file. minio.enable: enabling means that object storage will be used to store images. If you disable this option, postgres will be used to store images. Note: If after the first deployment a certain number of images have already been collected, you should not disable this option, since then you won't be able to obtain this data. This option must be disabled for AWS deployment. matcher.shard_n: interface parameter, regulates the number of simultaneous calls to matcher-serivice. Must be equal to the shard.quantity parameter in the matcher.values.yaml file
./cfg/matcher.values.yaml	shard.quantity: the number of shards to be created; increasing the parameter allows you to speed up searches on large data shard.search_threads_n: the number of threads used to perform the search
./cfg/baf.secrets.json	baf-user-secret: credentials (email address and password) that will be used to access BAF. Please note that the minimum password length is 6 characters, the password must consist of Latin letters and numbers, at least one capital letter and the special character “!”. platform-token: token for connecting to OMNI Platform. baf-postgres: data for connecting to the database. ATTENTION! Field platform-token filled in during installation.
./cfg/baf.values.yaml	video_recorder.enabled: the switch for working with Video Recorder. Set 0 if you do not plan to work with Video Recorder. ingress.rules.gateway.host: domain used in ingress to route requests to Kubernetes services for BAF. postgres.pool_size: the size of connection pool. You may need to increase it if you expect a high load on BAF services.
./cfg/platform-ui.values.yaml	ingress.host: domain name, used in ingress to route requests to Kubernetes services. The value must match the value of ingress.rules.gateway.host in the ./cfg/platform.values.yaml file.
./cfg/video-recorder.secrets.json	video-recorder-tokens: access token and encryption token. video-recorder-postgres: data for connecting to the database. video-recorder-minio: data for connecting to object storage. ATTENTION!: the video-recorder-tokens fields are filled in during installation.
./cfg/video-recorder.values.yaml	minio.data_retention_days: data retention period in days in object storage (Video, reference frames, templates). minio.enable: disable if using your own minio. You need to change the values for lrs-minio in the ./cfg/lrs.secrets.json file and the values for minio.host, minio.port and minio.secure (1 for https, 0 for http) in the current file. video_recorder.obtain_ref_frame: disable for better performance if you don't need to compare frames from a video. video_recorder.mock_video_recording: enable for better performance if you do not need to view recorded videos. Videos that are 4 bytes in size will continue to be saved for system stability, but will not be played back. lrs.enable: disable for performance enhancement if you do not need video liveness calculations. Video liveness will continue to be saved for system stability, but will always have a value of 99. video_recorder.uvicorn_concurrency: number of simultaneously processed http requests for each pod. After exceeding the limit a 503 error will be returned. video_recorder.sqlalchemy_pool_size: the maximum number of persistent connections that the sql alchemy pool will hold for each pod. video_recorder.sqlalchemy_pool_overflow: the number of connections on top of the persistence quantity that will be closed after use for each pod. video_recorder.max_webrtc_simultaneous_conn: number of WebRTC sessions processed simultaneously for each pod. After exceeding the limit, errors 503 will be returned on connection attempts. minio.buckets_prefix: prefix, which is placed before all names of bucket in this format: <prefix>.<bucket name>
./cfg/stunner.secrets.json	stunner-auth-secret.type: credentials type. Should always be ephemeral. stunner-auth-secret.secret: secret that will be used to generate TURN connection credentials.
./cfg/decoder.values.yaml	core.decoding_process_count: number of decoding processes launched within a single service replica. Increasing this value allows the service to handle more simultaneous video decoding sessions.
./cfg/report.values.yaml	core.process_count: number of report-building processes. Increasing this value enables the system to generate more reports simultaneously.

Updating configuration of a running instance

To apply updates to module values, run the module installation command. If the update doesn't take effect, uninstall and reinstall the module.

For updates involving module resources (e.g., secrets), execute the module resource installation command. Then, restart the module pods using Kubernetes tools to ensure they pick up the changes.

Extended configuration (optionally)

Docker settings for GPU usage

To set nvidia-container-runtime as the default low-level runtime, add the following lines to the configuration file located at /etc/docker/daemon.json:

{
 "default-runtime": "nvidia",
 "runtimes": {
   "nvidia": {
     "path": "/usr/bin/nvidia-container-runtime",
     "runtimeArgs": []
     }
   }
 }

To apply configuration, restart docker-service using the command below:

$ sudo systemctl restart docker

Check that the docker service is running successfully:

$ sudo systemctl status docker

Configuring GPU usage in BAF

To enable GPU in BAF you need to edit the file ./cfg/image-api.values.yaml. To do this, set 1 in the variable processing.services.face-detector-template-extractor.configs.recognizer.params.use_cuda:

Set 1 for processing.services.face-detector-template-extractor.resources.limits.gpu:

Install and configure a cluster

note

If you already have a deployed cluster, move to Configure licensing section.

To create and configure the cluster, run the following commands:

./cli.sh smc system-patch
./cli.sh smc install
./cli.sh platform db-create-mountpoint
./cli.sh platform install-secrets

This commands:

• Create database mount point.
• Initialize a cluster.
• Install the secrets.

To use GPU in a cluster, install NVIDIA device plugin:

$ ./cli.sh smc nvidia install

Cluster health check

After initializing the master node, make sure that all nodes are ready for operation and have the Ready status. You can check this by running the command below:

$ kubectl get nodes

As a result, the following output will be displayed in the terminal:

NAME          STATUS      ROLES                   AGE     VERSION
master-node   Ready       control-plane,master    11d     v1.23.8

To check all cluster components, run the following command:

$ kubectl get all --all-namespaces

Configure licensing

The user has 3 license activation options: trial period activation, online and offline license activation.

Install and run a license server

Before installation, open the license-server.settings.cfg file and set the IP address of the machine, on which the license server will be installed, in the license_server_address field.

Run the command below to install the license server. If license_server_address differs from the host address of the machine where the deployment is taking place, it will be set via sshpass.

$ ./cli.sh license-server install

Check that the license server is in the Running status:

$ ./cli.sh license-server status

Console output example:

floatingserver.service - Floating License Server
    Loaded: loaded (/etc/systemd/system/floatingserver.service; enabled; vendor preset: enabled)
    Active: active (running) since Tue 2022-12-20 12:25:54 +05; 1min 48s ago

To check that the license server is available, follow http://<license_server_address>:8090 in your web browser. As a result, you should be redirected to the login form.

Trial period activation

Please note that:

• The Internet connection is required.
• Running on a virtual machine is not allowed.

The trial period is activated the first time you launch BAF.

Online license activation

Before activation, make sure that the key field (from file ./cfg/license-server.settings.cfg) contains the license key.

Run the license activation command:

$ ./cli.sh license-server activate

When license is successfully activated, the console will return the following result:

[2022-12-20 12:25:53+05:00] INF Activating license key...
[2022-12-20 12:25:54+05:00] INF License activated successfully!

Offline license activation

Before activation, make sure that the license_key field (from file ./cfg/license-server.settings.cfg) contains the license key.

note

For offline activation, set "1" in the enable_offline_activation field in the license-server.settings.cfg file.

Run the command below to generate an offline license request:

$ ./cli.sh license-server generate-offline

As a result, the request-offline.dat file should appear in the setup directory.

Send the generated request-offline.dat request file to baf-request@3divi.com. The license file will be submitted in the response email.

Copy the received license file to the setup folder.

Open the configuration file license-server.settings.cfg in a text editor and fill in the variable license_offline_activation_file with the license file name and its extension, if present, separated by a dot.

Run the license activation command:

$ ./cli.sh license-server activate

When license is successfully activated, the console will return the following result:

[2022-09-08 01:30:36+05:00] INF Offline activating license key...
[2022-09-08 01:30:36+05:00] INF License activated successfully!

Deployment

Launch deployment

Install facial recognition subsystem (OMNI Platform)

Run the installation of the first OMNI Platform module:

$ ./cli.sh image-api install

Install matcher (matcher-router + matcher-shard):

./cli.sh matcher install

Run the installation of the second OMNI Platform module:

$ ./cli.sh platform install

If necessary, run the installation of OMNI Platform web interface:

./cli.sh platform-ui install

To continue the installation, open the /etc/hosts file and add the following lines at the end of the file:

<external_ip_address> : <platform_domain>
<external_ip_address> : <baf_domain>

Install the Video Recorder (VR) subsystem (optional)

If you do not need to record video, skip this step

In the Registration by Selfie scenario Video Recorder provides the ability to save video attempts and perform Motion Control.

Create a directory to store the object store data using the command:

$ ./cli.sh video-recorder minio-create-mountpoint

Run the command to generate Video Recorder tokens:

$ ./cli.sh video-recorder generate-token

Example of output to the console:

sha256:2473ba0ebf5ef66cd68b252bba7b46ae9f7cc3657b5acd3979beb7fbc5d8807f
Fernet key: ......
Access token: ......

As a result, you will get two tokens that need to be written in the configuration file ./cfg/video-recorder.secrets.json in the section video-recorder-tokens.

Run the command to install the Video Recorder secrets:

$ ./cli.sh video-recorder install-secrets

Run the command to install the Video Recorder:

$ ./cli.sh video-recorder install

Install the subsystem for estimation of Liveness Reflection (LRS) (optional)

note

LRS will not work without the Video Recorder subsystem

The LRS subsystem is necessary for calculating liveness through video. If liveness reflection is not required for your application, you can skip this step.

In the Registration by Selfie scenario LRS provides the ability to detect a video stream injection attack.

Run the command to install the LRS:

$ ./cli.sh lrs install

Install the Decoder Service (DS) video decoding subsystem (optional)

note

The Decoder Service requires the Video Recorder subsystem to function.

The Decoder Service is essential for video decoding. If cross-matching functionality is not needed, you can skip this step.

To install the Decoder Service, run:

$ ./cli.sh decoder install

Install the stunner subsystem for proxying requests through TURN server to Video Recorder (optional)

The stunner subsystem is required to establish WebRTC connections between client browsers and the Video Recorder (VR) server for video recording and liveness calculation. If you're not using WebRTC or if the VR module is not installed, you can skip this step.

Run the command to install stunner secrets:

$ ./cli.sh stunner install-secrets

Run the command to install the stunner:

$ ./cli.sh stunner install

Use the following commands to verify that the stunner is running:

$ kubectl get pods | grep stunner
$ kubectl get svc | grep -P 'tcp|udp|stunner'

If all pods have a Running status and 5 services are running, then stunner is running successfully.

Run the command to obtain the ports on which the TURN server is accessible from the outside:

$ ./cli.sh stunner get-ports

Example output of the command:

tcp-gateway: 31021
udp-gateway: 30796

Install BAF

Get a token from OMNI Platform:

$ ./cli.sh platform get-token - http://<platform_domain> <platform_user_email>

As a result, you will receive a token that must be written to the configuration file ./cfg/baf.secrets.json in the platform-token section.

Next, initialize the BAF secrets for the cluster:

$ ./cli.sh baf install-secrets

Run BAF installation:

$ ./cli.sh baf install

To monitor the deployment process, open another terminal tab and enter the following command:

$ watch 'kubectl get pods'

BAF is running if all pods have the Running status.

Install the Report Service (RS) reporting subsystem (optional)

The RS subsystem is needed for generating reports on system performance. If reporting functionality is not required, you can skip this step.

To install the Report Service, run the following command:

$ ./cli.sh report install

Configure DNS server

To provide access to BAF, DNS server on your network should contain a record that domain is available at <external_ip_address>.

For testing you need to fill in IP address and domain in the /etc/hosts file on Linux or C:\Windows\System32\drivers\etc\hosts on Windows.

To do this, add a new line like <external_ip_address> <host> at the end of this file, set the values for the corresponding variables and save the file. Note that you need to have administrator privileges to edit the hosts file.

Scalability

When the load increases, the following services can be scaled in manual mode to stabilize BAF operation:

• image-api-liveness-estimator is the service used to detect a face and determine if the face in the image is real or fake.
• image-api-age-estimator is the service used to estimate a person’s age from a face image.
• image-api-gender-estimator is the service used to estimate a person’s gender from a face image.
• image-api-mask-estimator is the service that detects if a person in the image is wearing a medical mask.
• image-api-emotion-estimator is the service that estimates a person's emotions from a face image.
• image-api-face-detector-template-extractor-dep is the service used to build face biometric templates.
• image-api-face-detector-face-fitter-dep is the service used for face detection and obtaining anthropomorphic face points.
• decoder-core is the service used for video decoding.
• video-recorder-video-recorder is the service used for saving recorded videos.
• lrs-lrs is the service used for calculating liveness from video.

To scale the service, run the command below:

$ kubectl scale deployment <SERVICE_NAME> --replicas <COUNT>

where SERVICE_NAME is a service name (for example, gateway-dep), and COUNT is a number of service instances.

To handle a load of A requests per second on a server with B physical CPU cores, when the input load contains validation with video recording and motion control (both videos having the following characteristics):

• format: webm
• codec: vp8
• resolution: 720p
• duration: 2.8 seconds
• frames per second: 13

You should scale the replicas of the following services based on the formula min(A, B):

• decoder-core
• video-recorder-video-recorder
• lrs-lrs
• image-api-face-detector-face-fitter-dep

For the image-api-face-detector-face-detector-template-extractor-dep service, use the scaling formula min(A*2, B).

If the server has a GPU installed, where C is the GPU RAM in megabytes and D is calculated as fix(C/1000), the image-api-face-detector-template-extractor-dep service should be scaled by min(A, D).

To save the scaling parameters, open the files ./cfg/platform.values.yaml, ./cfg/image-api.values.yaml, ./cfg/lrs.values.yaml, ./cfg/video-recorder.values.yaml and ./cfg/decoder.values.yaml, find the replicas field in the service block and specify the new replica values.

During next installations services will be automatically scaled to the specified values.