Before launching#

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

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

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

Docker installation#

Docker is required for launching of the FaceStream container.

The Docker installation is described in the official documentation:

https://docs.docker.com/engine/install/centos/.

You do not need to install Docker if you already have an installed Docker of the latest version on your server.

Quick installation commands are listed below.

Check the official documentation for updates if you have any problems with the installation.

Install dependencies.

yum install -y yum-utils device-mapper-persistent-data lvm2

Add repository.

yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

Install Docker.

yum -y install docker-ce docker-ce-cli containerd.io

Launch Docker.

systemctl start docker

systemctl enable docker

Check Docker status.

systemctl status docker

Docker Compose installation#

Note. Install Docker Compose only if you are going to use the FaceStream automatic launching script.

Install Docker Compose.

curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

chmod +x /usr/local/bin/docker-compose

ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

See the official documentation for details:

https://docs.docker.com/compose/install/

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.

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.

Enter login .

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

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

The login and password are received from VisionLabs.

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.

License key activation#

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

Launching LP services#

Note. Before launching LP services, make sure that the license is activated (see the "License key activation when LP is not launched" section).

The launch of LUNA PLATFORM services is necessary if the following additional components are not launched:

InfluxDB OSS 2
PostgreSQL
LUNA Configurator service
LUNA Licenses service

If the above components are already launched, skip this section.

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

Create a database for LUNA Configurator:

docker exec -i postgres psql -U luna -c "CREATE DATABASE luna_configurator;"

Allow the user to log in to the database:

docker exec -i postgres psql -U luna -c "GRANT ALL PRIVILEGES ON DATABASE luna_configurator TO luna;"

LUNA Configurator DB initialization#

Use the docker run command with these parameters to create the 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 \
-v /var/lib/fs/fs-current/extras/conf/configurator_configs/platform_settings.json:/srv/luna_configurator/used_dumps/platform_settings.json \
--network=host \
--rm \
--entrypoint bash \
dockerhub.visionlabs.ru/luna/luna-configurator:v.2.0.82 \
-c "python3 ./base_scripts/db_create.py; cd /srv/luna_configurator/configs/configs/; python3 -m configs.migrate --config /srv/luna_configurator/configs/config.conf head; cd /srv; python3 ./base_scripts/db_create.py --dump-file /srv/luna_configurator/used_dumps/platform_settings.json"

/var/lib/fs/fs-current/extras/conf/configurator_configs/platform_settings.json - enables you to specify the path to the dump file with LP configurations.

./base_scripts/db_create.py; - creates database structure.

python3 -m configs.migrate head; - performs settings migrations in Configurator DB and sets revision for migration.

--dump-file /srv/luna_configurator/used_dumps/platform_settings.json - updates settings in the Configurator DB with values from the provided file.

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/fs-current/extras/conf/configurator_configs/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.