Skip to content

Launching FaceStream#

You can run FaceStream in one of the following ways:

Examples of running FaceStream are given in the sections below.

By default, the CPU is used for calculations. It is possible to run FaceStream in the above ways using GPU. The section "Command for launching container using GPU" provides an example of starting a container in server mode with Configurator using GPU. For the other modes, launching the container using the GPU is similar.

FaceStream can be started in face or body detection mode. To switch modes, use the "use-face-detector" and "use-body-detector" settings from the trackengine.conf configuration file or the TRACK_ENGINE_CONFIG section in the Configurator.

One of the settings should be equal to "1". By default, FaceStream works in face detection mode.

You cannot enable both settings at the same time.

You can create new configuration files based on existing configuration files (fs3config.conf, input.json) and specify them when starting FaceStream (in launching keys). This way you can create multiple configuration files for different purposes without changing the default s.

Never use configuration files from other FaceStream versions! FaceStream will not start, or the processing results will differ from the expected.

Launching FaceStream in server mode with Configurator#

Configuring FaceStream before launching#

Launching FaceStream in server mode using the Configurator does not require the use of standard configuration files, except for the faceengine.conf file. You should use this file when running in server mode.

The rest of the FaceStream settings can be set in the Configurator service after its launch.

Video streams for FaceStream in server mode are created using the FaceStream API after it is launched (see FaceStreamApi.html).

Configurator service installation#

LUNA Configurator is an additional service of LUNA PLATFORM 5 and is distributed with it. All information on its installation and configuration can be found in the platform documentation.

You must install and configure LUNA Configurator before the FaceStream launching.

Uploading FaceStream settings into Configurator#

To configure FaceStream via Configurator, use one of the following files:

  • luna_configurator_dump.json - the file is provided as an example of setting without parameters from the input.json file. It is recommended to use this file when starting FaceStream.

  • luna_configurator_dump_with_streams_example.json - the file is provided as an example of setting with parameters from the input.json file. It enables you to set the video streams that FaceStream will start processing at startup.

Both files are located in the "conf/configurator_configs" directory. You should specify the necessary values in them before performing the following steps.

To upload FaceStream settings to the Configurator service, follow these steps.

You should perform the following commands on the server with LUNA Configurator.

  • Copy the file with FaceStream settings (for example, "luna_configurator_dump.json") to the server where the Configurator service is deployed.

  • Next, the file with FaceStream settings should be copied to the Configurator container.

docker cp <path_to_dump_file>/luna_configurator_dump.json luna-configurator:/srv/

<path_to_dump_file> - the directory with the "luna_configurator_dump.json" file.

  • You should apply settings using the following command:
docker exec luna-configurator python3.9 ./base_scripts/db_create.py --dump-file /srv/luna_configurator_dump.json

This feature is available starting version 0.0.3 of LUNA Configurator.

All the required parameters will be automatically added to Configurator.

Commands for launching container in server mode with Configurator#

Command for launching container using CPU#

Note. If the license was activated by the offline method, then you should additionally add the licenseFile.v2c file using the following parameter -v /var/lib/fs/fs-current/license/licenseFile.v2c:/srv/facestream/data/licenseFile.v2c during the container launch.

The container is launched as follows:

docker run \
--env=CONFIGURATOR_HOST=127.0.0.1 \
--env=CONFIGURATOR_PORT=5070 \
-v /var/lib/fs/fs-current/license/license.conf:/srv/facestream/data/license.conf \
-v /var/lib/fs/fs-current/conf/configs/faceengine.conf:/srv/facestream/data/faceengine.conf \
-v /etc/localtime:/etc/localtime:ro \
-v /var/lib/fs/fs-current/logs/:/srv/logs/ \
--env=PORT=34569 \
--detach=true \
--restart=always \
--name=facestream \
--network=host \
dockerhub.visionlabs.ru/luna/facestream:v.5.0.7

For a description of the remaining parameters and launching keys, see the relevant sections below.

Command for launching container using GPU#

This section provides a command to launch FaceStream using GPU only for server mode with Configurator. The procedure for starting FaceStream in GPU mode is similar for other FaceStream operation modes.

Note. Use this command only if you are going to use FaceStream with GPU.

Before launching FaceStream in GPU mode, additional dependencies should be installed (see "GPU dependencies installation" section).

Before starting the FaceStream container with GPU, it is required to enable GPU for calculations in the FaceStream settings using the "enable_gpu_processing" parameter (see the "FaceStream configuration" section in the administrator manual).

Note. If the license was activated by the offline method, then you should additionally add the licenseFile.v2c file using the following parameter -v /var/lib/fs/fs-current/license/licenseFile.v2c:/srv/facestream/data/licenseFile.v2c during the container launch.

docker run \
--env=CONFIGURATOR_HOST=127.0.0.1 \
--env=CONFIGURATOR_PORT=5070 \
-v /var/lib/fs/fs-current/license/license.conf:/srv/facestream/data/license.conf \
-v /var/lib/fs/fs-current/conf/configs/faceengine.conf:/srv/facestream/data/faceengine.conf \
-v /etc/localtime:/etc/localtime:ro \
-v /var/lib/fs/fs-current/logs/:/srv/logs/ \
--env=PORT=34569 \
--gpus device=0 \
--detach=true \
--restart=always \
--name=facestream \
--network=host \
dockerhub.visionlabs.ru/luna/facestream:v.5.0.7

--gpus device=0 - the parameter specifies the used GPU device and enables GPU utilization. A single GPU can be utilized per FaceStream instance. Multiple GPU utilization per instance is not available.

For a description of the remaining parameters and launching keys, see the relevant sections below.

Launching keys for server mode with Configurator#

To launch FaceStream in server mode with Configurator, the keys are set using environment variables:

--env= - this parameter sets the environment variables required to start the container. The following basic values are specified:

  • CONFIGURATOR_HOST=127.0.0.1 - host on which the Configurator service is running. The local host is set if the container is running on the same server where the Configurator is running.

  • CONFIGURATOR_PORT=5070 - listening port for the Configurator service. By default, port 5070 is used.

  • PORT=34569 - port where FaceStream will listen.

  • STREAMS_ID="" - is used to set a LUNA Configurator tag, which relates to the video sources configuration.

If the value equals " " then saving/loading data about the sources of the video stream in LUNA Configurator will not be performed.

The ID of video stream should be specified in the Configurator service to use the stream. When the video stream is added using the API request, the ID is generated automatically.

If you specify a nonexistent tag, then a new record based on the FS_STREAMS record will be created in LUNA Configurator with the specified tag.

If the FS_STREAMS tag is not specified, the information about the video stream specified in the Configurator service is not used in FaceStream.

By default, the value equals " ".

To use this key, the Configurator service should be used. The variables CONFIGURATOR_HOST andCONFIGURATOR_PORT should be specified.

  • CONFIGS_ID="" - is used to set a LUNA Configurator tag, which relates to the FaceStream main configurations. The same tag should be set for TRACK_ENGINE_CONFIG and FACE_STREAM_CONFIG.

If the value is set to " " then the TRACK_ENGINE_CONFIG and FACE_STREAM_CONFIG records will be used by default. If the record by default does not exist or has an invalid JSON syntax, the configuration file from the distribution package will be used.

By default, the value equals " ".

To use this key, the Configurator service should be used. The variables CONFIGURATOR_HOST andCONFIGURATOR_PORT should be specified.

Description of container launch parameters#

docker run - command to launch the selected image as a new container.

-v - enables you to load the contents of the server folder into the volume of the container. This way the content is synchronized.

-v /var/lib/fs/fs-current/license/license.conf:/srv/facestream/data/license.conf \ - enables you to add a license activation file to the FaceStream container.

-v /var/lib/fs/fs-current/logs/:/srv/logs/ \ - enables you to copy the folder with FaceStream logs to the server in the directory /var/lib/fs/fs-current/logs/. The directory for storing logs can be changed if necessary.

--network=host - this parameter specifies that there is no network simulation and a server network is used. If you need to change the port for third-party containers, replace this line with -p 5440:5432. Here, the first port 5440 is the local port, and 5432 is the port used in the container.

/etc/localtime:/etc/localtime:ro - sets the current time zone used by the container system.

--name=facestream - this parameter specifies the name of the container to be launched. The name must be unique. If a container with the same name already exists, an error will occur.

--restart=always - this parameter defines the restart policy. Daemon always restarts the container regardless of the completion code.

--detach=true - running the container in the background.

Launching FaceStream in normal mode#

Configuring FaceStream before launching#

FaceStream can be launched in normal mode using the following configuration files:

  • input.json (see the description of the settings in the "Video-stream sources configuration" section of the administrator manual)
  • fs3Config.conf (see the description of the settings in the "FaceStream configuration" section of the administrator manual)
  • trackengine.conf (see the description of the settings in the "Trackengine configuration" section of the administrator manual)
  • faceengine.conf

You should first set all the necessary parameters in these files before launching FaceStream.

FaceStream can be launched in normal mode using GPU. The "Command for launching container using GPU" section provides an example of starting a container in server mode with Configurator using GPU.

Command for launching container in normal mode#

Note. If the license was activated by the offline method, then you should additionally add the licenseFile.v2c file using the following parameter -v /var/lib/fs/fs-current/license/licenseFile.v2c:/srv/facestream/data/licenseFile.v2c during the container launch.

The container is launched as follows:

docker run \
-v /var/lib/fs/fs-current/license/license.conf:/srv/facestream/data/license.conf \
-v /var/lib/fs/fs-current/conf/configs/input.json:/srv/facestream/data/input.json \
-v /var/lib/fs/fs-current/conf/configs/fs3Config.conf:/srv/facestream/data/fs3Config.conf \
-v /var/lib/fs/fs-current/conf/configs/faceengine.conf:/srv/facestream/data/faceengine.conf \
-v /var/lib/fs/fs-current/conf/configs/trackengine.conf:/srv/facestream/data/trackengine.conf \
-v /var/lib/fs/fs-current/logs/:/srv/logs/ \
-v /etc/localtime:/etc/localtime:ro \
--name=facestream \
--network=host \
--restart=always \
--detach=true \
--entrypoint /srv/facestream/FaceStreamStatic \
dockerhub.visionlabs.ru/luna/facestream:v.5.0.7 \
--source-path /srv/facestream/data/input.json \
--config-path /srv/facestream/data/fs3Config.conf \
--data-dir /srv/facestream/data \
--log-dir /srv/facestream/logs

Launching keys for normal mode#

To launch FaceStream in normal mode inside the container, the following command is used, which enables you to specify the correct paths to directories inside the container.

--entrypoint /srv/facestream/FaceStreamStatic \
dockerhub.visionlabs.ru/luna/facestream:v.5.0.7 \
--source-path /srv/facestream/data/input.json \
--config-path /srv/facestream/data/fs3Config.conf \
--data-dir /srv/facestream/data \
--log-dir /srv/facestream/logs

The following keys are available:

  • --source-path – path to the configuration file of video-stream sources. You should specify the path to "input.json" file.

  • --config-path – full path to the configuration file "fs3Config.conf" of the application. If this parameter is defined, the path to data is ignored when searching for the configuration file.

  • --data-dir – path to the directory with detectors and settings data.

  • --log-dir – directory to record logging files.

Description of container launch parameters#

docker run - command to launch the selected image as a new container.

-v - enables you to load the contents of the server folder into the volume of the container. This way the content is synchronized.

The configuration files are included in the FaceStream package in the "conf/config/" directory and are added to the container at launch with the following commands:

-v /var/lib/fs/fs-current/conf/configs/input.json:/srv/facestream/data/input.json \
-v /var/lib/fs/fs-current/conf/configs/fs3Config.conf:/srv/facestream/data/fs3Config.conf \
-v /var/lib/fs/fs-current/conf/configs/faceengine.conf:/srv/facestream/data/faceengine.conf \
-v /var/lib/fs/fs-current/conf/configs/trackengine.conf:/srv/facestream/data/trackengine.conf \

-v /var/lib/fs/fs-current/license/license.conf:/srv/facestream/data/license.conf \ - enables you to add a license activation file to the FaceStream container.

-v /var/lib/fs/fs-current/logs/:/srv/logs/ \ - enables you to copy the folder with FaceStream logs to the server in the directory /var/lib/fs/fs-current/logs/. The directory for storing logs can be changed if necessary.

--network=host - this parameter specifies that there is no network simulation and a server network is used. If you need to change the port for third-party containers, replace this line with -p 5440:5432. Here, the first port 5440 is the local port, and 5432 is the port used in the container.

/etc/localtime:/etc/localtime:ro - sets the current time zone used by the container system.

--name=facestream - this parameter specifies the name of the container to be launched. The name must be unique. If a container with the same name already exists, an error will occur.

--restart=always - this parameter defines the restart policy. Daemon always restarts the container regardless of the completion code.

--detach=true - running the container in the background.

Launching FaceStream in server mode with configuration files#

Configuring FaceStream before launching#

FaceStream can be launched in server mode with settings from configuration files using the following configuration files:

  • fs3Config.conf (see the description of the settings in the "FaceStream configuration" section of the administrator manual)
  • trackengine.conf (see the description of the settings in the "Trackengine configuration" section of the administrator manual)
  • faceengine.conf

The configuration file "input.json" is not used when starting FaceStream. Video streams are created using the FaceStream API after it is launched (see FaceStreamApi.html).

You should first set all the necessary parameters in these files before launching FaceStream.

FaceStream can be launched in normal mode using GPU. The "Command for launching container using GPU" section provides an example of starting a container in server mode with Configurator using GPU.

Command for launching container in server mode with configuration files#

Note. If the license was activated by the offline method, then you should additionally add the licenseFile.v2c file using the following parameter -v /var/lib/fs/fs-current/license/licenseFile.v2c:/srv/facestream/data/licenseFile.v2c during the container launch.

The container is launched as follows:

docker run \
-v /var/lib/fs/fs-current/license/license.conf:/srv/facestream/data/license.conf \
-v /var/lib/fs/fs-current/conf/configs/fs3Config.conf:/srv/facestream/data/fs3Config.conf \
-v /var/lib/fs/fs-current/conf/configs/faceengine.conf:/srv/facestream/data/faceengine.conf \
-v /var/lib/fs/fs-current/conf/configs/trackengine.conf:/srv/facestream/data/trackengine.conf \
-v /etc/localtime:/etc/localtime:ro \
-v /var/lib/fs/fs-current/logs/:/srv/logs/ \
--restart=always \
--detach=true \
--name=facestream \
--network=host \
--env=PORT=34569 \
--entrypoint /srv/facestream/FaceStream \
dockerhub.visionlabs.ru/luna/facestream:v.5.0.7 \
--config-path /srv/facestream/data/fs3Config.conf \
--data-dir /srv/facestream/data \
--log-dir /srv/facestream/logs \
--http-address http://0.0.0.0:34569

Launching keys for server mode with configuration files#

To launch FaceStream in server mode with configuration files inside the container, the following command is used, which enables you to specify the correct paths to directories inside the container.

--entrypoint /srv/facestream/FaceStream \
dockerhub.visionlabs.ru/luna/facestream:v.5.0.7 \
--config-path /srv/facestream/data/fs3Config.conf \
--data-dir /srv/facestream/data \
--log-dir /srv/facestream/logs \
--http-address http://0.0.0.0:34569

The following keys are available:

  • --config-path – full path to the configuration file "fs3Config.conf" of the application. If this parameter is defined, the path to data is ignored when searching for the configuration file.

  • --data-dir – path to the directory with detectors and settings data.

  • --log-dir – directory to record logging files.

  • --http-address - HTTP address that FaceStream will listen to. It is set in the format "address:port" (used only for FaceStream in server mode). The user will send requests to this address.

You should set the external IP of the FaceStream server. By default, it is set to «http://0.0.0.0:34569».

Description of container launch parameters#

docker run - command to launch the selected image as a new container.

-v - enables you to load the contents of the server folder into the volume of the container. This way the content is synchronized.

The configuration files are included in the FaceStream package in the "conf/config/" directory and are added to the container at launch with the following commands:

-v /var/lib/fs/fs-current/conf/configs/fs3Config.conf:/srv/facestream/data/fs3Config.conf \
-v /var/lib/fs/fs-current/conf/configs/faceengine.conf:/srv/facestream/data/faceengine.conf \
-v /var/lib/fs/fs-current/conf/configs/trackengine.conf:/srv/facestream/data/trackengine.conf \

-v /var/lib/fs/fs-current/license/license.conf:/srv/facestream/data/license.conf \ - enables you to add a license activation file to the FaceStream container.

-v /var/lib/fs/fs-current/logs/:/srv/logs/ \ - enables you to copy the folder with FaceStream logs to the server in the directory /var/lib/fs/fs-current/logs/. The directory for storing logs can be changed if necessary.

--network=host - this parameter specifies that there is no network simulation and a server network is used. If you need to change the port for third-party containers, replace this line with -p 5440:5432. Here, the first port 5440 is the local port, and 5432 is the port used in the container.

/etc/localtime:/etc/localtime:ro - sets the current time zone used by the container system.

--name=facestream - this parameter specifies the name of the container to be launched. The name must be unique. If a container with the same name already exists, an error will occur.

--restart=always - this parameter defines the restart policy. Daemon always restarts the container regardless of the completion code.

--detach=true - running the container in the background.

Back to top