Before upgrade#

Make sure that you are the root user before upgrade!

Before upgrading the LUNA PLATFORM, you must perform the following actions:

See key changes from previous versions if you are upgrading from a version other than LUNA PLATFORM 5.38.1
Create backups
Prepare to change the version of the neural network to extract descriptors if necessary
Delete old symbolic link
Unpack the distribution of the new version of LUNA PLATFORM
Create new symbolic link
Change group and owner for new directories
Move old buckets of the Image Store service
Move old data of the PostgreSQL DB
Move old data of the Influx DB
Save user configurations of the Configurator service if they have changed
Configure SELinux and Firewall if not previously configured
Create log directories for new services if you have previously used logging to file
Perform license activation steps if necessary
Set up GPU computing if you plan to use GPU
Login to VisionLabs registry if authorization was not previously performed
Remove old containers

Key changes from previous versions#

Note. When updating LUNA PLATFORM from a previous version, skip this section.

The following are the key changes from previous versions that you should pay attention to when updating from older versions of LUNA PLATFORM. Some of these changes require mandatory actions to be performed, otherwise the LUNA PLATFORM may not start or function incorrectly.

Not all changes are listed in the table below. See the LUNA PLATFORM release notes for details on all changes.

Version	Changes	Mandatory actions
5.38.3	The default value of the "score_threshold" setting in the "LUNA_HANDLERS_BODY_DETECTOR_SETTINGS" section of the Configurator service has been changed from 0.89 to 0.42.	Check the body recognition logic if the "score_threshold" value is used that is different from the default value.
	The default value of the "redetect_face_target_size" setting in the "LUNA_HANDLERS_FACE_DETECTOR_SETTINGS" section of the Configurator service has been changed from 0.89 to 0.42.	Check the face recognition logic if the "redetect_face_target_size" value is used that is different from the default value.
5.36.5	The address of the license server must now be set in the Configurator settings before starting the Licenses container.	Perform the steps described in the "Specify license server address using Configurator" section.
5.35.0	Support for old Services for index building and searching by index has been discontinued.	-
5.34.0	The 54, 56 and 57 neural network models for extracting face descriptors have been removed from the Handlers container.	Read the information described in the section "Prepare to change the neural network version", and perform certain actions before launching Handlers if one of the listed models was used.
	The 104 and 106 neural network models for extracting body descriptors has been removed from the Handlers container. Now the 107 model is used by default.	Read the information described in the section "Prepare to change the neural network version", and perform certain actions before launching Handlers, because the default version has changed.
	Support for the Liveness V1 service has been discontinued.	-
5.30.0	Vendor libraries for HASP key and HASP utility have been updated (from 111186 to 30147).	Update the HASP service and issue a new license (see "License key activation").
	The mechanism for creating and managing accounts has been changed.	Perform actions marked with the phrase Note! Accounts migration (upgrading from 5.2.0...5.28.0 only)
5.28.0	The default value of the "score_threshold" setting in the "FACE_DETECTOR_V3" section of the Configurator service has been changed from 0.89 to 0.42.	Check the face recognition logic if the "score_threshold" value is used that is different from the default value.
5.26.0	The presence of a mask on the chin from this version refers to the "missing" state. In previous versions, it referred to the "medical_mask" state.	Check the logic of the mask estimation.
5.24.0	Support for the Vertica database for the Events service has been discontinued.	-
5.23.0	The default thresholds (recommended) have been updated for the following checks in the “face_quality” section and the “/iso” resource: "mouth_occluded" (old values: min=0, max=0.3; new values: min=0, max=0.5) and "mouth_open" (old values: min=0, max=0.64; new values: min=0, max=0.5)	Check the logic of "mouth_occluded" and "mouth_open" if the default values were used.
5.14.0	The Liveness V2 algorithm has been updated. The default thresholds for “liveness_threshold” and “quality_threshold” are now “0.5". The recommended threshold “liveness_threshold” is now “0.5” instead of “0.88".	Check the logic of the Liveness V2 algorithm.
5.6.0	Now, by default, the neural network model 59 for extracting face descriptors is used.	Read the information described in the section "Prepare to change the neural network version", and perform certain actions before launching Handlers, because the default version has changed.
	The 101 model of the neural network for extracting body descriptors has been removed from the Handlers container. Now the 104 model is used by default.	Read the information described in the section "Prepare to change the neural network version", and perform certain actions before launching Handlers, because the default version has changed.
5.3.0	The logic of launching LUNA PLATFORM services inside containers has been changed. Now applications are launched not from the "root" user, but from the "luna" user.	-
	Support for FaceDetV1 and FaceDetV2 detectors has been discontinued.	-

Create backups#

It is recommended to create the following backups:

backups of all databases used with LUNA PLATFORM (not described in this documentation);
backup of Image Store buckets (not described in this documentation);
backup of LUNA PLATFORM services configurations.

Creating backups will enable you to restore in case of any problems during the migration process.

Backup of LUNA PLATFORM services configurations#

Custom configurations for LUNA PLATFORM services (all except the Configurator service) are automatically migrated using the Configurator service migration mechanism. This backup will not be used during the normal installation of LUNA PLATFORM.

If your previous LP version was used with non-default other LUNA PLATFORM services configurations, backup the service configurations dump-file in the separate directory on your server outside the Configurator container.

Do not replace the dump-file /var/lib/luna/current/extras/conf/platform_settings.json provided in the distribution packages with this file.

To create a dump-file, use the following options (may be executed from anywhere on your server):

wget -O /var/lib/luna/settings_dump_backup.json 127.0.0.1:5070/1/dump

or

curl 127.0.0.1:5070/1/dump > /var/lib/luna/settings_dump_backup.json

Prepare to change the neural network version#

Note. If you are upgrading from LUNA PLATFORM 5.38.1, skip the steps below.

In the LUNA PLATFORM 5.34.0 build, the neural network models 54, 56, 57, 104 and 106 for extracting face and body descriptors were removed from the Handlers container. In addition, the neural network model for extracting body descriptor by default has changed from 104 to 107. If you are upgrading from versions 5.2.0 and higher and in the previous build, one of the removed models was specified in the settings "DEFAULT_FACE_DESCRIPTOR_VERSION" or "DEFAULT_HUMAN_DESCRIPTOR_VERSION", then the launch of the Handlers service will fail if you do not perform the additional steps.

There are available models of neural networks for extracting descriptors in the current LUNA PLATFORM build:

Object from which descriptor is extracted	Neural network models	Default model
Face	58, 59, 60	59
Body	102, 105, 107	107

It is necessary to perform one of the additional actions depending on the following scenarios of the work:

Continuation of the use of missing neural networks

Request to VisionLabs an old neural network model and prepare it for transfer to the new Handlers container after its launch (see instructions in the section "Use non-delivery neural network model" of administrator manual).

Switching to new version of the neural network with continuation of the use of old descriptors

run the "Additional extraction" task before the update (see "Additional extraction task" in the administrator manual). This will convert old descriptors to a new version of the neural network.
specify the new version of the neural network in the settings "DEFAULT_FACE_DESCRIPTOR_VERSION" or "DEFAULT_HUMAN_DESCRIPTOR_VERSION" before launching the Handlers service (see section "Change the neural network model for extracting descriptors").

Switching to new version of the neural network with cessation of the use of old descriptors

Specify the new version of the neural network in the settings "DEFAULT_FACE_DESCRIPTOR_VERSION" or "DEFAULT_HUMAN_DESCRIPTOR_VERSION" before launching the Handlers service (see section "Change the neural network model for extracting descriptors").

If it is not necessary to extract body descriptors, then you can disable the use of the neural network using the command --env=EXTEND_CMD="--enable-body-descriptor-estimator=0" when launching Handlers container (see the detailed information in the section "Enable/disable several estimators and detectors" of the administrator manual).

Delete old symbolic link#

Delete the symbolic link to the previous minor version directory using the following command:

rm -f /var/lib/luna/current

Distribution unpacking#

The distribution package is an archive luna_v.5.38.3, where v.5.38.3 is a numerical identifier, describing the current LUNA PLATFORM version.

The archive includes configuration files, required for installation and exploitation. It does not include Docker images for the services. They should be downloaded from the Internet.

Move the distribution package to the directory on your server before the installation. For example, move the files to /root/ directory. The directory should not contain any other distribution or license files except the target ones.

Create directory for distribution file unpacking

mkdir -p /var/lib/luna

Move the distribution to the created directory

mv /root/luna_v.5.38.3.zip /var/lib/luna

Install the unzip archiver if it is necessary

yum install -y unzip

Go to the folder with distribution

cd /var/lib/luna

Unzip files

unzip luna_v.5.38.3.zip

Symbolic link creation#

Create a symbolic link. The link indicates that the current version of the distribution file is used to run LUNA PLATFORM.

ln -s luna_v.5.38.3 current

Changing group and owner for directories#

LP services are launched inside the containers by the "luna" user. Therefore, it is required to set permissions for this user to use the mounted volumes.

Go to the LP "example-docker" directory:

cd /var/lib/luna/current/example-docker/

Set permissions for the user with UID 1001 and group 0 to use the mounted directories.

mkdir luna_configurator/used_dumps

chown -R 1001:0 luna_configurator/used_dumps

chown -R 1001:0 image_store

Move data#

Move the data for your databases to the directory with new distribution.

It is considered, that you use the default paths for storing databases and buckets.

The example is provided for updating from version 5.38.1. You should perform these actions for the LP build installed on your server. Change v.5.38.1 in commands below to your currently installed build.

You should copy the data folder of your database from "luna_v.5.38.1" directory to the current root. Thus you can use your data in the new LP build.

Move Image Store bucket#

The following step is required if you are storing Image Store buckets in the default directory.

Copy the "image_store" folder with all its buckets:

cp -r /var/lib/luna/luna_v.5.38.1/example-docker/image_store /var/lib/luna/current/example-docker/

Set rights for the luna user:

chown -R 1001:0 /var/lib/luna/current/example-docker/image_store

Move PostgreSQL data#

The following step is required if you are using PostgreSQL in Docker container.

Copy the "data" folder:

cp -r /var/lib/luna/luna_v.5.38.1/example-docker/postgresql/data /var/lib/luna/current/example-docker/postgresql/

Move InfluxDB Data#

The following step is required if you are using InfluxDB in Docker container.

Copy the "influx" folder with all its buckets:

cp -r /var/lib/luna/luna_v.5.38.1/example-docker/influx /var/lib/luna/current/example-docker/

Note! Starting from version 5.9.0, InfluxDB OSS version 2 is used by default. This version enables you to visualize monitoring data using Grafana. If necessary, you can migrate data from InfluxDB version 1 to InfluxDB version 2. See https://docs.influxdata.com/influxdb/v2.0/upgrade/v1-to-v2/docker/.

Save user configurations of the Configurator#

The configurations of the Configurator service are not automatically migrated, unlike the configurations of all other services.

If your previous LP version was used with non-default Configurator service configurations, back up your "/var/lib/luna/current/example-docker/luna_configurator/configs/luna_configurator_postgres.conf" config file in the separate directory on your server.

cp /var/lib/luna/current/example-docker/luna_configurator/configs/luna_configurator_postgres.conf /var/lib/luna/BACKUP_luna_configurator_postgres.conf

This backup must be mounted to the Configurator service container that is being run.

If you are not sure if the Configurator service configurations have changed, you can compare the created backup with the Configurator configurations from the current distribution using the following command:

diff /var/lib/luna/<your_previous_lp_version>/example-docker/luna_configurator/configs/luna_configurator_postgres.conf /var/lib/luna/BACKUP_luna_configurator_postgres.conf

SELinux and Firewall#

You must configure SELinux and Firewall so that they do not block LUNA PLATFORM services.

SELinux and Firewall configurations are not described in this guide.

If SELinux and Firewall are not configured, the installation cannot be performed

Create log directory for new services#

Skip this section if no logs were previously stored on the server.

In the new version of LUNA PLATFORM, new services could appear, for which you need to create directories with logs. It depends on the version from which you are upgrading. For example, version 5.30.0 introduced the Accounts service.

See "Logging to server" section if you have not previously used logging to a file, but want to enable it.

Following are the commands to create directories for all existing services. These commands will create and assign permissions only to missing directories.

mkdir -p /tmp/logs/configurator /tmp/logs/image-store /tmp/logs/accounts /tmp/logs/faces /tmp/logs/licenses /tmp/logs/events /tmp/logs/python-matcher /tmp/logs/handlers /tmp/logs/tasks /tmp/logs/tasks-worker /tmp/logs/sender /tmp/logs/api /tmp/logs/admin /tmp/logs/backport3 /tmp/logs/backport4

chown -R 1001:0 /tmp/logs/configurator /tmp/logs/image-store /tmp/logs/accounts /tmp/logs/faces /tmp/logs/licenses /tmp/logs/events /tmp/logs/python-matcher /tmp/logs/handlers /tmp/logs/tasks /tmp/logs/tasks-worker /tmp/logs/sender /tmp/logs/api /tmp/logs/admin /tmp/logs/backport3 /tmp/logs/backport4

If you need to use the Python Matcher Proxy service, then you need to additionally create the /tmp/logs/python-matcher-proxy directory and set its permissions.

License key activation#

The HASP service is used for LUNA PLATFORM licensing. Without a license, you will be unable to run and use LUNA services.

A HASP key is required to work with LUNA PLATFORM. It uses the haspvlib_x86_64_30147.so vendor library, which located in the in the "/var/hasplm/" directory.

License key is provided by VisionLabs separately upon request.

A network license is required to use LUNA PLATFORM in Docker containers.

The license key is created using the fingerprint. The fingerprint is created based on the information about hardware characteristics of the server. Therefore, the received license key will only work on the same server where the fingerprint was obtained.

There is a possibility that a new license key will be required when you perform any changes on the license server.

LP license includes the following features:

License expiration date.
Maximum number of faces with linked descriptors or basic attributes.
Liveness availability.
Liveness current balance.
Image check according to ISO/IEC 19794-5 standard availability.
Body parameters estimation availability.
Possibility of using the Index Matcher service in the LUNA Index Module.
Maximum number of streams created by the LUNA Streams service.

When ordering the license, you need to inform technical support about the need to use any of the above features.

Follow these steps to set up the license:

Install HASP utility on your server. HASP utility is usually installed on a separate server;
Start the HASP utility;
Create the fingerprint of your server and send it to VisionLabs;
Activate your key, received from VisionLabs;
Specify your HASP server address in the Configurator settings before starting the Licenses container (see "Specify license server address using Configurator").

The Sentinel Keys tab of the user interface (<server_host_address>:1947) shows activated keys.

Install HASP utility#

LP uses HASP utility of a certain version.

If an older version of HASP utility is installed, it is required to delete it before installation of a new version. See Delete old LP hasp utility.

Go to the HASP directory.

cd /var/lib/luna/current/extras/hasp/

Install HASP utility on you server.

yum -y install /var/lib/luna/current/extras/hasp/aksusbd-*.rpm

Launch HASP utility.

systemctl daemon-reload

systemctl start aksusbd

systemctl enable aksusbd

systemctl status aksusbd

Configure HASP utility#

You can configure the HASP utility using the "/etc/hasplm/hasplm.ini" file.

Note! You do not need to perform this action if you already have the configured INI file for the HASP utility.

Delete the old file if necessary.

rm -rf /etc/hasplm/hasplm.ini

Copy the INI file with configurations. Its parameters are not described in this document.

cp /var/lib/luna/current/extras/hasp/hasplm.ini /etc/hasplm/

Add vendor library#

Copy LP vendor library (x32 and x64). This library is required for using LP license key.

cp /var/lib/luna/current/extras/hasp/haspvlib_30147.so /var/hasplm/

cp /var/lib/luna/current/extras/hasp/haspvlib_x86_64_30147.so /var/hasplm/

Restart the utility

systemctl restart aksusbd

Create fingerprint#

Go to the HASP directory.

cd /var/lib/luna/current/extras/hasp/licenseassist

Run the script

./LicenseAssist fingerprint > fingerprint_30147.c2v

The fingerprint is saved to file "fingerprint_30147.c2v".

Send the file to VisionLabs. You license key will be created using this fingerprint.

You can also save the system fingerprint from the user interface at <host_address>:1947 by clicking the "Fingerprint" button on the "Sentinel Keys" tab.

Add license file manually using user interface#

Go to: <host_address>:1947 (if access is denied check your Firewall/ SELinux settings (the procedure is not described in this document);
Select the Update/Attach at the left pane;
Press the "Select File..." button and select a license file(s) in the appeared window;
Press the "Apply File" button.

Delete LP old hasp utility#

Note. Delete the HASP utility only if you need to install a newer version. Otherwise, skip this step.

Stop and disable the utility.

systemctl stop aksusbd

systemctl disable aksusbd

systemctl daemon-reload

yum -y remove aksusbd haspd

Calculations using GPU#

You can use GPU for the general calculations performed by Handlers.

Skip this section if you are not going to utilize GPU for your calculations.

You need to install NVIDIA Container Toolkit to use GPU with Docker containers. The example of the installation is given below.

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)

curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.repo | tee /etc/yum.repos.d/nvidia-docker.repo

yum install -y nvidia-container-toolkit

systemctl restart docker

Check the NVIDIA Container toolkit operating by running a base CUDA container (this container is not provided in the LP distribution and should be downloaded from the Internet):

docker run --rm --gpus all nvidia/cuda:11.4-base nvidia-smi

See the documentation for additional information:

https://github.com/NVIDIA/nvidia-docker#centos-7x8x-docker-ce-rhel-7x8x-docker-ce-amazon-linux-12.

Attributes extraction on the GPU is engineered for maximum throughput. The input images are processed in batches. This reduces computation cost per image but does not provide the shortest latency per image.

GPU acceleration is designed for high load applications where request counts per second consistently reach thousands. It won’t be beneficial to use GPU acceleration in non-extensively loaded scenarios where latency matters.

When launching containers, you should specify a link to the image required for the container launching. This image will be downloaded from the VisionLabs registry. Before that, you should login to the registry.

Login and password can be requested from the VisionLabs representative.

Enter login .

docker login dockerhub.visionlabs.ru --username <username>

After running the command, you will be prompted for a password. Enter password.

In the docker login command, you can enter the login and password at the same time, but this does not guarantee security because the password can be seen in the command history.

Remove old containers#

Before launching the containers of the current minor version, stop all LUNA PLATFORM related containers of the previous minor version and third-party software containers.

Third-party containers can also be removed as their versions can be updated in new build.

PostgreSQL and InfluxDB require restarting even if their containers were not changed. This is related to the transfer of their data folders. See "Move data".

To delete a container use the next command:

docker container rm -f [container_name]

where [container_name] is the service docker container name or ID.

For example, to remove LP containers only use the following command:

docker container rm -f luna-configurator luna-backport3 luna-backport4 luna-sender  luna-tasks luna-handlers  luna-python-matcher luna-events luna-licenses luna-faces luna-image-store luna-ui-3 luna-ui-4 luna-admin luna-api luna-tasks-worker luna-accounts

To see the containers names or IDs, use the following command:

docker ps -a

It is also recommended to delete old images of the containers to free space. You can use the following command to delete all unused images.

If there is enough space on the server it is recommended to perform this action only after new version of LP is successfully launched.

The command deletes all the unused images, not only the images related to LP.

docker image prune -a -f