Skip to main content

# 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/image-api.values.json | processing.enable_ingress: set this parameter to 1 to provide external access to the image-api module via an Ingress resource. The Ingress will use the domain from the ingress.host parameter. ingress.host: the domain name used in the Ingress to route requests to the Kubernetes services for the image-api module.
./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.enable — set this parameter to 1 to provide external access to the OMNI Platform module via an Ingress resource. The Ingress will use the domain from the ingress.rules.gateway.host parameter. 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-service. Must be equal to the shard.quantity parameter in the matcher.values.yaml file. backend.planned_retention_policy_day_of_week: day of the week in cron format when the periodic cleanup task will be launched. backend.planned_retention_policy_hour: hour in cron format when the periodic cleanup task will be launched. backend.planned_retention_policy_minute: minute in cron format when the periodic cleanup task will be launched. backend.delete_sample_batch_size: size of the attempt's frame batch that will be deleted at once. backend.delete_sample_batch_sleep: time in seconds between batch deletions. backend.retention_process_count: number of processes performing attempt's frame cleanup. backend.sample_ttl: time in seconds beyond which attempt's frames will be deleted.
./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-postgres: data for connecting to the database. baf-email-secret: data for connecting to the SMTP server. ATTENTION! Field platform-token filled in during installation.
./cfg/baf.values.yaml | 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.error_data_retention_days: period of storage of erroneous data in days in the object store. minio.enable: disable if using your own minio. You need to change the values for video-recorder-minio in the ./cfg/video_recorder.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.webrtc_mock_video_recording: the parameter is enabled 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. This works only in recording mode via WebRTC. 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> decoder.enabled: disable if you do not need to decode video. decoder.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. minio.delete_cleanup_interval: interval at which minio deletes objects from the trash. video_recorder.retention_batch_size: size of the attempt video content batch that will be deleted at once. video_recorder.retention_batch_pause: time in seconds between batch deletions. video_recorder.retention_process_count: number of processes performing attempt's video content cleanup. video_recorder.retention_check_frequency: frequency of cleanup check execution in seconds.
./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/report.values.yaml | core.process_count: number of report-building processes. Increasing this value enables the system to generate more reports simultaneously.
./cfg/util-services.values.yaml | ingress.rules.gateway.host: must be equal to ingress domain in ./cfg/baf.values.yaml

#### 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, run the following command:

    ./cli.sh smc nvidia install

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

These 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

note

For the platform-ui module to work, you need to enable the Ingress for the OMNI Platform module (parameter ingress.enable in the ./platform.values.yaml file).

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)​

danger

If you are updating from version 1.12.0, make sure to transfer the motion control patterns, if necessary, to the settings of the new version. If you do not do this before installing the new version of the video recorder, the pattern data will be irretrievably lost.

For detailed information, see the Update Instructions section.

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

note

The pattern mechanism has been updated in version 1.13.0. Please refer to updates to transfer patterns between versions.

Run the command to install 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.
danger

To use the system, you need to create a user. For more information, see User management instructions section.

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

#### Install the Util Services (US) subsystem (optional)​

The US subsystem is required to run optional services for monitoring BAF operations.

To install Util Services, run the command below:

    $ ./cli.sh util-services 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.