Install Step-by-Step

This section will guide you through the FindFace Enterprise Server step-by-step installation process. Follow the instructions below minding the sequence.

In this section:

Install APT Repository

First of all, install the FindFace apt repository as follows:

1. Download the installer file <findface-security-and-server-xxx>.run.

2. Put the .run file into some directory on the designated host (for example, /home/username).

3. From this directory, make the .run file executable.

   chmod +x <findface-security-and-server-xxx>.run
   

4. Execute the .run file.

   sudo ./<findface-security-and-server-xxx>.run
   

   The installer will ask you a few questions and perform several automated checks to ensure that the host meets the system requirements. Fill out the prompts appropriately once requested. The questions are the following:

   1. Product to install: FindFace Server.

   2. Installation type: repo: Don't install anything, just set up the APT repository.

   3. Neural network models to install if necessary. To select a model(s), deselect all those on the list by entering -* in the command line first, then select the required model by entering its sequence number (keyword): for example, 1 3. Enter done to save your selection and proceed to another step.

      Important

      At least one model for face biometry has to be installed.

   After that, the FindFace apt repository will be automatically installed.

Prerequisites

FindFace Enterprise Server requires such third-party software as etcd and memcached. Do the following:

1. Install the prerequisite packages as such:

   sudo apt update
   sudo apt install -y etcd memcached
   

2. Open the memcached configuration file. Set the maximum memory to use for items in megabytes: -m 512. Set the max item size: -I 16m. If one or both of these parameters are absent, add them to the file.

   sudo vi /etc/memcached.conf
   
   -m 512
   -I 16m
   

3. Enable the prerequisite services autostart and launch the services:

   sudo systemctl enable etcd.service memcached.service
   sudo systemctl start etcd.service memcached.service
   

Provide Licensing

You receive a license file from your Ntech Lab manager. If you opt for the on-premise licensing, we will also send you a USB dongle.

The FindFace Enterprise Server licensing is provided as follows:

1. Deploy findface-ntls, license server in the FindFace core.

   sudo apt update
   sudo apt install -y findface-ntls
   sudo systemctl enable findface-ntls.service && sudo systemctl start findface-ntls.service
   

   Important

   There must be only one findface-ntls instance in each FindFace Enterprise Server installation.

   Tip

   In the findface-ntls configuration file, you can change the license folder and specify your proxy server IP address if necessary. You can also change the findface-ntls web interface remote access settings. See findface-ntls for details.

2. Upload the license file via the findface-ntls web interface in one of the following ways:

   • Navigate to the findface-ntls web interface http://<NTLS_IP_address>:3185/#/. Upload the license file.

     Tip

     Later on, use the findface-ntls web interface to consult your license information, and upgrade or extend your license.

   • Directly put the license file into the license folder (by default, /ntech/license, can be changed in the /etc/findface-ntls.cfg configuration file).

3. For the on-premise licensing, insert the USB dongle into a USB port.

4. If the licensable components are installed on remote hosts, specify the IP address of the findface-ntls host in their configuration files. See findface-extraction-api, findface-tarantool-server, Video face detection: findface-video-manager and findface-video-worker for details.

See also

Troubleshoot Licensing and findface-ntls

Deploy findface-extraction-api

To deploy the findface-extraction-api component, do the following:

Important

This component requires the installation of neural network models.

1. Install findface-extraction-api as such:

   sudo apt install -y findface-extraction-api
   

   Note

   To install the GPU-accelerated findface-extraction-api component, use findface-extraction-api-gpu in the command.

2. Open the findface-extraction-api.ini configuration file.

   sudo vi /etc/findface-extraction-api.ini
   

3. Specify the IP address of the findface-ntls host if findface-ntls is installed on a remote host. See Provide Licensing.

   license_ntls_server: 192.168.113.2:3133
   

4. Configure other parameters if needed. For example, enable or disable fetching Internet images.

   fetch:
     enabled: true
     size_limit: 10485760
   

5. The min_face_size and max_face_size parameters do not work as filters. They instead indicate the guaranteed detection interval. Pick up their values carefully as these parameters affect performance.

   nnd:
     min_face_size: 30
     max_face_size: .inf
   

6. The instances parameter indicates how many findface-extraction-api instances are used. Specify the number of instances from your license. The default value (0) means that this number is equal to the number of CPU cores.

   Note

   This parameter severely affects RAM consumption.

   instances: 2
   

7. To estimate the face quality, enable the quality_estimator. In this case, extraction-api will return the quality score in the detection_score parameter.

   Tip

   Interpret the quality score further in analytics. Upright faces in frontal position are considered the best quality. They result in values around 0, mostly negative (such as -0.00067401276, for example). Inverted faces and large face angles are estimated with negative values some -5 and less.

   quality_estimator: true
   

8. Enable recognition models for face features such as gender, age, emotions, glasses3, and/or beard, subject to your needs. Be sure to choose the right acceleration type for each model, matching the acceleration type of findface-extraction-api: CPU or GPU. Be aware that findface-extraction-api on CPU can work only with CPU-models, while findface-extraction-api on GPU supports both CPU- and GPU-models.

   models:
     age: faceattr/age.v1.cpu.fnk
     emotions: faceattr/emotions.v1.cpu.fnk
     face: face/grapefruit_480.cpu.fnk
     gender: faceattr/gender.v2.cpu.fnk
     beard: faceattr/beard.v0.cpu.fnk
     glasses3: faceattr/glasses3.v0.cpu.fnk
   

   The following models are available:

   Face feature	Acceleration	Configuration file parameter
   face (biometry)	CPU	face: face/grapefruit_480.cpu.fnk
   	GPU	face: face/grapefruit_480.gpu.fnk
   age	CPU	age: faceattr/age.v1.cpu.fnk
   	GPU	age: faceattr/age.v1.gpu.fnk
   gender	CPU	gender: faceattr/gender.v2.cpu.fnk
   	GPU	gender: faceattr/gender.v2.gpu.fnk
   emotions	CPU	emotions: faceattr/emotions.v1.cpu.fnk
   	GPU	emotions: faceattr/emotions.v1.gpu.fnk
   glasses3	CPU	glasses3: faceattr/glasses3.v0.cpu.fnk
   	GPU	glasses3: faceattr/glasses3.v0.gpu.fnk
   beard	CPU	beard: faceattr/beard.v0.cpu.fnk
   	GPU	beard: faceattr/beard.v0.gpu.fnk

   Tip

   To disable a recognition model, pass an empty value to a relevant parameter. Do not remove the parameter itself as in this case the system will be searching for the default model.

   models:
     gender: ""
     age: ""
     emotions: ""
   

9. Enable the findface-extraction-api service autostart and launch the service.

   sudo systemctl enable findface-extraction-api.service && sudo systemctl start findface-extraction-api.service
   

Deploy findface-tarantool-server

The findface-tarantool-server component connects the Tarantool database and the findface-sf-api component, transferring search results from the database to findface-sf-api for further processing. To increase search speed, multiple findface-tarantool-server shards can be created on each Tarantool host. Their running concurrently leads to a remarkable increase in performance. Each shard can handle up to approximately 10,000,000 faces. In the case of the standalone deployment, you need only one shard (already created by default). In a cluster environment, the number of shards has to be calculated depending on your hardware configuration and database size (see details below).

To deploy the findface-tarantool-server component, do the following:

1. Install findface-tarantool-server

   sudo apt update
   sudo apt install -y findface-tarantool-server
   

2. Disable autostart and stop the Tarantool exemplary service.

   sudo systemctl disable tarantool@example && sudo systemctl stop tarantool@example
   

3. Open the configuration file:

   sudo vi /etc/tarantool/instances.enabled/FindFace.lua
   

4. Edit the maximum memory usage. The memory usage must be set in bytes, depending on the number of faces the shard handles, at the rate roughly 1280 byte per face. For example, the value 1.2*1024*1024*1024 corresponds to 1,000,000 faces:

   memtx_memory = 1.2 * 1024 * 1024 * 1024,
   

5. Specify the IP address of the findface-ntls host if findface-ntls is installed on a remote host:

   FindFace.start(“127.0.0.1”, 8001, {license_ntls_server=“192.168.113.2:3133”})
   

6. By default, you can access Tarantool only from the localhost (127.0.0.1). If you plan to be accessing Tarantool from a certain remote host, either specify this remote host IP address in the FindFace.start section, or change 127.0.0.1 to 0.0.0.0 in the same section to allow access to Tarantool from any IP address.

   Tip

   To allow access only from a certain remote host (192.168.113.10 in the example), configure as follows:

   FindFace.start("192.168.113.10", 8001, {license_ntls_server=“192.168.113.2:3133”})
   

   To allow access from any IP address, apply 0.0.0.0 instead:

   FindFace.start("0.0.0.0", 8001, {license_ntls_server=“192.168.113.2:3133”})
   

7. In the meta_scheme parameter, create a database structure to store the face recognition results. The structure is created as a set of fields. Describe each field with the following parameters:

   • id: field id;

   • name: field name, must be the same as the name of a relevant face parameter;

   • field_type: data type;

   • default: field default value. If a default value exceeds ‘1e14 – 1’, use a string data type to specify it, for example, "123123.." instead of 123123...

   box.cfg{
       listen = '127.0.0.1:33001',
   
       vinyl_dir = '/opt/ntech/var/lib/tarantool/name',
       work_dir = '/opt/ntech/var/lib/tarantool/name',
       memtx_dir = '/opt/ntech/var/lib/tarantool/name/snapshots',
       wal_dir = '/opt/ntech/var/lib/tarantool/name/xlogs',
   
       memtx_memory = 16 * 1024 * 1024 * 1024,
   
       checkpoint_interval = 3600*4,
       checkpoint_count = 3,
   
       -- force_recovery = true,
   }
   
   pcall(function() box.schema.user.grant('guest', 'execute,read,write', 'universe') end)
   
   FindFace = require("FindFace")
   FindFace.start(
       "0.0.0.0",
       8001,
       {
           license_ntls_server="127.0.0.1:3133",
           facen_size=480,
           meta_scheme  = {
   
               {
                   id = 1,
                   name = 'm:timestamp',
                   field_type = 'unsigned',
                   default = 0
               },
   
               {
                   id = 2,
                   name = 'feat',
                   field_type = 'string',
                   default = ""
               },
   
               {
                   id = 3,
                   name = 'normalized_id',
                   field_type = 'string',
                   default = ""
               },
   
               {
                   id = 4,
                   name = 'm:camera',
                   field_type = 'string',
                   default = ""
               },
   
               {
                   id = 5,
                   name = 'm:photo',
                   field_type = 'string',
                   default = ""
               },
   
               {
                   id = 6,
                   name = 'm:thumbnail',
                   field_type = 'string',
                   default = ""
               },
   
               {
                   id = 7,
                   name = 'm:score',
                   field_type = 'unsigned',
                   default = "10000000000000000000"
               },
   
               {
                   id = 8,
                   name = 'm:bbox',
                   field_type = 'string',
                   default = ""
               },
   
               {
                   id = 9,
                   name = 'm:labels',
                   field_type = 'set[string]',
                   default = {}
               },
   
               {
                   id = 10,
                   name = 'm:is_friend',
                   field_type = 'unsigned',
                   default = 0
               },
               }
       }
   )
   

8. (Optional) If there are more than 10,000,000 faces or so on a single shard, the search may take too long. In the case of a large installation, it is advised to create additional findface-tarantool-server shards, observing the following rules:

   • One shard can successfully handle up to approximately 10,000,000 faces.

   • The number of shards on a single host must not exceed the number of CPU memory channels, multiplied by 2. Bear it in mind, when designing your system architecture in a cluster environment.

   To create multiple shards, multiply the configuration file for the default shard /etc/tarantool/instances.enabled/FindFace.lua. Then override the default shard IP address and port with new values. To do so, write a bash script (e.g., shard.sh) that will automatically create configuration files for all shards on a particular host. The script below can be used as an excellent starting point for your own code. The exemplary script creates 4 shards listening to the ports: findface-tarantool-server 33001..33004 and HTTP 8001..8004.

   #!/bin/sh
   set -e
   
   for I in `seq 1 4`; do
          TNT_PORT=$((33000+$I)) &&
          HTTP_PORT=$((8000+$I)) &&
          sed "
                  s#/opt/ntech/var/lib/tarantool/default#/opt/ntech/var/lib/tarantool/shard_$I#g;
                  s/listen = .*$/listen = '127.0.0.1:$TNT_PORT',/;
                  s/\"127.0.0.1\", 8001,/\"0.0.0.0\", $HTTP_PORT,/;
          " /etc/tarantool/instances.enabled/FindFace.lua > /etc/tarantool/instances.enabled/FindFace_shard_$I.lua;
   
          mkdir -p /opt/ntech/var/lib/tarantool/shard_$I/snapshots
          mkdir -p /opt/ntech/var/lib/tarantool/shard_$I/xlogs
          mkdir -p /opt/ntech/var/lib/tarantool/shard_$I/index
          chown -R tarantool:tarantool /opt/ntech/var/lib/tarantool/shard_$I
          echo "Shard #$I inited"
   done;
   

   Tip

   Download the exemplary script.

   Run the script from the home directory.

   sudo sh ~/shard.sh
   

   Check the configuration files created.

   ls /etc/tarantool/instances.enabled/
   
   ##example.lua FindFace.lua FindFace_shard_1.lua FindFace_shard_2.lua FindFace_shard_3.lua FindFace_shard_4.lua
   

9. Enable the findface-tarantool-server shard autostart and launch the shard.

   sudo systemctl enable tarantool@FindFace.service && sudo systemctl start tarantool@FindFace.service
   

   In the case of multiple shards, you can do so by analogy with the following example (launching 4 shards):

   for I in `seq 1 4`; do sudo systemctl enable tarantool@FindFace_shard_$I; done;
   for I in `seq 1 4`; do sudo systemctl start tarantool@FindFace_shard_$I; done;
   

Deploy findface-upload

To store all original images ever sent to the system for processing, as well as such FindFace core artifacts as face thumbnails and normalized images, you will need the findface-upload service.

Tip

Skip the findface-upload deployment if you do not want to store these data on the FindFace Enterprise Server host. In this case, the system will be saving only face features vectors (biometric samples) in the Tarantool-powered biometric database.

Install findface-upload as such:

sudo apt update
sudo apt install -y findface-upload

By default, the original images, thumbnails, and normalized images are stored at /var/lib/ffupload/uploads/.

Deploy findface-sf-api

To deploy the findface-sf-api component, do the following:

1. Install findface-sf-api as such:

   sudo apt update
   sudo apt install -y findface-sf-api
   

2. Open the /etc/findface-sf-api.ini configuration file.

   sudo vi /etc/findface-sf-api.ini
   

3. If FindFace Enterprise Server is being deployed in a cluster environment, specify the IP addresses and ports of the findface-extraction-api host (the extraction-api parameter), the findface-tarantool-server shards (storage-api, in the format: http://IP_address:port/v2/), and the findface-upload host (upload_url).

   extraction-api:
     extraction-api: http://10.220.85.120:18666
   storage-api:
    shards:
    - master: http://10.200.85.115:8003/v2/
    - master: http://10.200.85.120:8004/v2/
    - master: http://10.200.85.120:8005/v2/
    - master: http://10.200.85.120:8006/v2/
      slave: ‘’
   upload_url: http://127.0.0.1:3333/uploads/
   

4. Enable the findface-sf-api service autostart and launch the service.

   sudo systemctl enable findface-sf-api.service && sudo systemctl start findface-sf-api.service
   

Deploy findface-facerouter

To deploy the findface-facerouter component, do the following:

1. Install findface-facerouter as such:

   sudo apt update
   sudo apt install -y findface-facerouter
   

2. Open the /etc/findface-facerouter.py configuration file.

   sudo vi /etc/findface-facerouter.py
   

3. If the findface-facerouter and findface-sf-api components are installed on different hosts, uncomment the sfapi_url parameter and specify the findface-sf-api host IP address.

   sfapi_url                      = 'http://localhost:18411'
   

4. Enable the findface-facerouter service autostart and launch the service.

   sudo systemctl enable findface-facerouter.service && sudo systemctl start findface-facerouter.service
   

Deploy Video Face Detection

Video face detection is provided by the findface-video-manager and findface-video-worker components.

To deploy the findface-video-manager component, do the following:

1. Install findface-video-manager:

   sudo apt install -y findface-video-manager
   

2. Open the /etc/findface-video-manager.conf configuration file.

   sudo vi /etc/findface-video-manager.conf
   

3. In the router_url parameter, specify the IP address and port of the findface-facerouter component which will receive detected faces from findface-video-worker.

   router_url: http://127.0.0.1:18820/v0/frame
   

4. In the ntls -> url parameter, specify the IP address of the findface-ntls host if findface-ntls is installed on a remote host.

   ntls:
       url: http://127.0.0.1:3185/
   

5. If necessary, configure the video processing settings which apply to all video streams in the system.

   Tip

   You can skip this step: when creating a job for findface-video-manager, you will be able to individually configure processing settings for each video stream (see Video Face Detection API).

6. Enable the findface-video-manager service autostart and launch the service.

   sudo systemctl enable findface-video-manager.service && sudo systemctl start findface-video-manager.service
   

To deploy the findface-video-worker component, do the following:

1. Install findface-video-worker:

   sudo apt update
   sudo apt install -y findface-video-worker-cpu
   

   Note

   To install the GPU-accelerated findface-video-worker component, use findface-video-worker-gpu in the command. If you have several video cards on your server, see Multiple Video Cards Usage.

2. Open the /etc/findface-video-worker-cpu.ini (/etc/findface-video-worker-gpu.ini) configuration file.

   sudo vi /etc/findface-video-worker-cpu.ini
   sudo vi /etc/findface-video-worker-gpu.ini
   

3. In the ntls-addr parameter, specify the IP address of the findface-ntls host if findface-ntls is installed on a remote host.

   ntls-addr=127.0.0.1:3133
   

4. In the mgr-static parameter, specify the IP address of the findface-video-manager host that will be providing findface-video-worker with settings and the list of to-be-processed video streams.

   mgr-static=127.0.0.1:18811
   

5. In the capacity parameter, specify the maximum number of video streams that findface-video-worker is allowed to process.

   capacity=10
   

6. Enable the findface-video-worker autostart and launch the service.

   sudo systemctl enable findface-video-worker-cpu.service && sudo systemctl start findface-video-worker-cpu.service