Before upgrading#

Before upgrading FaceStream, you need to complete a number of additional steps.

Create backup#

Create backups for the LUNA Streams database before performing the migration procedures. You can restore your data if any problems occur during the migration.

Backups creation for database is not described in this document.

Create copy of LUNA Configurator settings#

To keep the Configurator settings used in the previous version of FaceStream, back up the configuration file /var/lib/fs/fs-current/extras/conf/configurator_configs/luna_configurator_postgres.conf in a separate directory on the server.

cp /var/lib/fs/fs-current/extras/conf/configurator_configs/luna_configurator_postgres.conf /var/lib/fs/BACKUP_luna_configurator_postgres.conf

Prepare dump file for migrations#

If the previous version of FaceStream was used with non-default settings for other services, back up the services settings file to a separate directory on the server outside of the Configurator service container.

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

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

or

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

It is not required to use this backup during the upgrade. It should be used only in case when something went wrong.

Delete symbolic link#

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

rm -f /var/lib/fs/fs-current

Unpacking#

It is recommended to move the archive to a pre-created directory for FaceStream and unpack the archive there.

The following commands should be performed under the root user.

Create a directory for FaceStream.

mkdir -p /var/lib/fs

Move the archive to the created directory. It is considered that the archive is saved to the "/root" directory.

mv /root/facestream_docker_v.5.1.14.zip /var/lib/fs/

Go to the directory.

cd /var/lib/fs/

Install the unzip utility if it is not installed.

yum install unzip

Unpack the archive.

unzip facestream_docker_v.5.1.14.zip

You will need to configure FaceStream before launching it.

The unpacked archive includes all the configuration files required for the FaceStream launch. The configuration parameters description is given further in this document.

Symbolic link creation#

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

ln -s facestream_docker_v.5.1.14 fs-current

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 v.5.1.13. You should perform these actions for the FaceStream build installed on your server. Change v.5.1.13 in commands below to your currently installed build.

You should copy the data folder of your database from "facestream_docker_v.5.1.13" directory to the current root. Thus you can use your data in the new FaceStream build.

Copy PostgreSQL data#

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

Copy the "data" folder:

cp -r /var/lib/fs/facestream_docker_v.5.1.13/example-docker/postgresql /var/lib/fs/fs-current/example-docker/

Copy 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/fs/facestream_docker_v.5.1.13/example-docker/influx /var/lib/fs/fs-current/example-docker/

Remove old containers#

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

PostgreSQL and InfluxDB 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 the FaceStream, LUNA Streams, LUNA Configurator, and LUNA Licenses containers, use the following command:

docker container rm -f facestream luna-streams luna-configurator luna-licenses

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 FaceStream is successfully launched.

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

docker image prune -a -f

Enable logging to file for FaceStream#

Note. Use the steps below only if you need to save logs to a file. By default, logs are output to the console. To view the logs from the console, use the docker logs <container_name> command.

If necessary, you can write the FaceStream logs in separate files. To do this, you should first create directory to save logs.

The log directory is created with the following command:

mkdir -p /var/lib/fs/fs-current/logs/

The directory for storing logs can be changed if necessary.

To enable logging, you should enable logging to a file in the FaceStream settings. To do this, you need to set the value of the "mode" parameter to "l2f" (output logs only to file) or "l2b" (output logs and file to the console).

To enable logging, you need to run the following command when starting the container:

-v /var/lib/fs/fs-current/logs/:/srv/logs/ \

Data from the specified folder is added to the Docker container when it is launched. All the data from the specified Docker container folder is saved to this directory.

To write LUNA service logs, follow the same steps.

By default, only system warnings are displayed in the FaceStream logs. By setting the "severity" parameter, you can enable error output (see the parameter description in the administrator manual).

GPU dependencies installation#

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

Actions to launch FaceStream with GPU through Docker Compose#

To launch FaceStream with GPU through Docker Compose, it is necessary, in addition to the above actions, to add the deploy section in the handlers field to the docker-compose.yml file.

vi /var/lib/fs/fs-current/example-docker/docker-compose.yml

  facestream:
    image: $:$/facestream:$
    deploy:
      resources:
        reservations:
          devices:
          - driver: nvidia
            count: all
            capabilities: [gpu]
    restart: always
    environment:
      CONFIGURATOR_HOST: $
      CONFIGURATOR_PORT: 5070

driver - this field specifies the driver for the reserved device(s);

count - this field specifies the number of GPU devices that should be reserved (providing the host holds that number of GPUs);

capabilities - this field expresses both generic and driver specific capabilities. It must be set, otherwise, an error will be returned when deploying the service.

See the documentation for additional information:

https://docs.docker.com/compose/gpu-support/#enabling-gpu-access-to-service-containers.

License key activation#

In most cases, there is no need to get a separate license when upgrading minor versions. The only time this may be needed is when updating a license. For example, the LP library has changed.

If the LUNA PLATFORM 5 license has not changed, skip this step.

License key activation when LP is launched#

If the LUNA PLATFORM services are already launched and the license with a parameter that determines the streams number for LUNA Streams operation is already activated, then you need to make sure that the current LUNA PLATFORM key contains this parameter. The information can be provided by VisionLabs specialists.

If this parameter is not contained in the key, then you need to request a new key and contact VisionLabs specialists for advice on updating the license key.

If LUNA Streams is launched on a server other than the one on which LUNA Licenses is launched, then you should perform the steps described in the section "Specifying LUNA Licenses server address".

License key activation when LP is not launched#

If the LUNA PLATFORM services are not launched or the launch is performed using Docker Compose, then it is assumed that the license has not yet been activated and it is necessary to request a new LUNA PLATFORM 5 license with a parameter determining the streams number for LUNA Streams operation, and go through the full LUNA PLATFORM 5 licensing process.

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

There is a HASP key that enables you to use LUNA PLATFORM and create streams in FaceStream. It uses the haspvlib_x86_64_30147.so vendor library.

You can find the vendor libraries in the "/var/hasplm/" directory.

License keys are provided by VisionLabs separately upon request. The utilized Liveness version is specified in the LUNA PLATFORM license key.

A network license is required to use LUNA PLATFORM and FaceStream 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.

Follow these steps:

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 a special file.

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

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 LP hasp utility".

Install HASP utility#

Go to the HASP directory.

cd /var/lib/fs/fs-current/extras/hasp/

Install HASP utility on you server.

yum -y install /var/lib/fs/fs-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/fs/fs-current/extras/hasp/hasplm.ini /etc/hasplm/

Add LP vendor library#

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

cp /var/lib/fs/fs-current/extras/hasp/haspvlib_30147.so /var/hasplm/

cp /var/lib/fs/fs-current/extras/hasp/haspvlib_x86_64_30147.so /var/hasplm/

Remove old version LP libraries if present:

rm -f /var/hasplm/haspvlib_x86_64_111186.so /var/hasplm/haspvlib_111186.so

Restart the utility

systemctl restart aksusbd

Create fingerprint for LUNA PLATFORM#

Go to the HASP directory.

cd /var/lib/fs/fs-current/extras/hasp/licenseassist

Add permissions to the script.

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.

Add a license file manually using user interface#

Go to: :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.

Specify license server address#

Specify your license service IP address in the configuration file in the following directory:

/var/lib/fs/fs-current/extras/hasp_redirect/

Change address to the HASP server in the following documents:

vi /var/lib/fs/fs-current/extras/hasp_redirect/hasp_30147.ini

Change the server address in "hasp_30147.ini" file.

serveraddr = <HASP_server_address>

The "hasp_30147.ini" file is used by the Licenses service upon its container launch. It is required to restart the launched container when the server is changed.

HASP_server_address - the IP address of the server with your HASP key. You must use an IP address, not a server name.

Delete LP hasp utility#

This action is performed to delete HASP utility.

Stop and disable the utility.

systemctl stop aksusbd

systemctl disable aksusbd

systemctl daemon-reload

yum -y remove aksusbd haspd

Upgrade and launch LP services#

InfluxDB OSS 2 container launching#

InfluxDB 2.0.8-alpine is required for LP monitoring purpose (for more information, see the "Monitoring" section in the LUNA PLATFORM administrator manual).

Note! If you already have InfluxDB 2.0.8-alpine installed, skip this step.

Use the docker run command with these parameters:

docker run \
-e DOCKER_INFLUXDB_INIT_MODE=setup \
-e DOCKER_INFLUXDB_INIT_BUCKET=luna_monitoring \
-e DOCKER_INFLUXDB_INIT_USERNAME=luna \
-e DOCKER_INFLUXDB_INIT_PASSWORD=password \
-e DOCKER_INFLUXDB_INIT_ORG=luna \
-e DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=kofqt4Pfqjn6o0RBtMDQqVoJLgHoxxDUmmhiAZ7JS6VmEnrqZXQhxDhad8AX9tmiJH6CjM7Y1U8p5eSEocGzIA== \
-v /etc/localtime:/etc/localtime:ro \
-v /var/lib/fs/fs-current/example-docker/influx:/var/lib/influxdb2 \
--restart=always \
--detach=true \
--network=host \
--name influxdb \
dockerhub.visionlabs.ru/luna/influxdb:2.0.8-alpine

PostgreSQL container launching#

If you already have PostgreSQL installed, skip this step.

Use the following command to launch PostgreSQL.

docker run \
--env=POSTGRES_USER=luna \
--env=POSTGRES_PASSWORD=luna \
--shm-size=1g \
-v /var/lib/fs/fs-current/example-docker/postgresql/data/:/var/lib/postgresql/data/ \
-v /var/lib/fs/fs-current/example-docker/postgresql/entrypoint-initdb.d/:/docker-entrypoint-initdb.d/ \
-v /etc/localtime:/etc/localtime:ro \
--name=postgres \
--restart=always \
--detach=true \
--network=host \
dockerhub.visionlabs.ru/luna/postgis-vlmatch:12

-v /var/lib/luna/current/example-docker/postgresql/data/:/var/lib/postgresql/data/ - the volume command enables you to mount the "data" folder to the PostgreSQL container. The folder on the server and the folder in the container will be synchronized. The PostgreSQL data from the container will be saved to this directory.

--network=host - if you need to change the port for PostgreSQL, you should change this string to -p 5440:5432. Where the first port 5440 is the local port and 5432 is the port used inside the container.

LUNA Configurator database migration#

The following instruction for migrating the LUNA Configurator service database assumes that the configuration migration revision is already installed in the database. The revision is set using the configs.migrate head; script. This script is included in the FaceStream installation manual. If the installation was performed according to the manual, no additional steps are required. Settings will be migrated automatically.

If there is no revision, you should re-create the database structure. See the FaceStream installation manual, section "LUNA Configurator DB initialization". Then you need to set all the necessary settings manually.

LUNA Configurator DB initialization#

When upgrading the LUNA Configurator database with existing settings, you should perform database structure migration and saved settings migration.

Your current database should already have settings migration revision.

Use the docker run command with these parameters to create the LUNA Configurator database tables.

docker run \
-v /etc/localtime:/etc/localtime:ro \
-v /var/lib/fs/fs-current/extras/conf/configurator_configs/luna_configurator_postgres.conf:/srv/luna_configurator/configs/config.conf \
--network=host \
--rm \
--entrypoint bash \
dockerhub.visionlabs.ru/luna/luna-configurator:v.2.0.82 \
-c "alembic upgrade head; cd /srv/luna_configurator/configs/configs/; python3 -m configs.migrate --config /srv/luna_configurator/configs/config.conf head;"

alembic upgrade head; - upgrades already existing database structure.

python3 -m configs.migrate head; - performs settings migrations in LUNA Configurator DB and sets revision for migration. The revision will be required during the upgrade to the new LUNA Configurator build.

LUNA Configurator container launching#

Use the docker run command with these parameters to launch Configurator:

docker run \
--env=PORT=5070 \
--env=WORKER_COUNT=1 \
--env=RELOAD_CONFIG=1 \
--env=RELOAD_CONFIG_INTERVAL=10 \
-v /etc/localtime:/etc/localtime:ro \
-v /var/lib/fs/BACKUP_luna_configurator_postgres.conf:/srv/luna_configurator/configs/config.conf \
--name=luna-configurator \
--restart=always \
--detach=true \
--network=host \
dockerhub.visionlabs.ru/luna/luna-configurator:v.2.0.82

LUNA Licenses container launching#

Make sure that you have specified the license server address in the "hasp_30147.ini" file. See section "Specify license server address".

Add the access right for the "luna" user to the "hasp_redirect" directory.

chown -R 1001:0 /var/lib/fs/fs-current/extras/hasp_redirect/

Use the following command to launch the service:

docker run \
--env=CONFIGURATOR_HOST=127.0.0.1 \
--env=CONFIGURATOR_PORT=5070 \
--env=PORT=5120 \
--env=WORKER_COUNT=1 \
--env=RELOAD_CONFIG=1 \
--env=RELOAD_CONFIG_INTERVAL=10 \
-v /etc/localtime:/etc/localtime:ro \
-v /var/lib/fs/fs-current/extras/hasp_redirect/hasp_30147.ini:/home/luna/.hasplm/hasp_30147.ini \
--name=luna-licenses \
--restart=always \
--detach=true \
--network=host \
dockerhub.visionlabs.ru/luna/luna-licenses:v.0.3.89

Specifying LUNA Licenses server address#

Note. Perform the following actions only if you launch LUNA Streams not on a server with LUNA Licenses. Otherwise, you can skip this step.

Go to the user interface of the LUNA Configurator service and select "luna-streams" from the "Service name" drop-down list.

In the "LUNA_LICENSES_ADDRESS" section, specify the address of the server where the LUNA Licenses service is launched.