.. _step-by-step:

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.
	
.. rubric:: In this section:

.. contents::
   :local:


Install APT Repository
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

#. Download the installer file ``findface-security-2.1.0-server-3.1.0.run``.
#. Put the ``.run`` file into some directory on the designated host (for example, ``/home/username``).
#. From this directory, make the ``.run`` file executable.

   .. code::

      chmod +x findface-security-2.1.0-server-3.1.0.run

#. Execute the ``.run`` file.

   .. code::

      sudo ./findface-security-2.1.0-server-3.1.0.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:

   #. Product to install: ``FindFace Server``. 
   #. Installation type: ``repo: Don't install anything, just set up the APT repository``.

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

.. important::
   As this installation type doesn't provide installation of neural network models essential for the ``findface-extraction-api`` functioning, be sure to :ref:`manually install <deploy-models>` them on the host(s) with ``findface-extraction-api``.


Prerequisites
^^^^^^^^^^^^^^^^^^^^^

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

#. Install the prerequisite packages as such:

   .. code::

      sudo apt update
      sudo apt install -y etcd memcached

#. 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, simply add them in the file.

   .. code::

      sudo vi /etc/memcached.conf 

      -m 512
      -I 16m

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

   .. code::

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


.. _licensing:

Provide Licensing
^^^^^^^^^^^^^^^^^^^^^^^^

You receive a license file from your NTechLab 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:

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

   .. 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 :ref:`ntls-config` for details.

   .. code::

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

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

          .. image: license_info.png

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

#. For the on-premise licensing, insert the USB dongle into a USB port.
#. If the licensable components are installed on remote hosts, specify the IP address of the ``findface-ntls`` host in their configuration files. See :ref:`extraction-api-config`, :ref:`tarantool-server-config`, :ref:`video-config` for details.


.. seealso::
    
    :ref:`troubleshoot-ntls`


.. _findface-extraction-api:

Deploy ``findface-extraction-api``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

.. important::
   This component requires installation of :ref:`neural network models <deploy-models>`. 

#. Install ``findface-extraction-api`` as such:

   .. code::

      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. 

#. Open the ``findface-extraction-api.ini`` configuration file.

   .. code::

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

#. Specify the IP address of the ``findface-ntls`` host if ``findface-ntls`` is installed on a remote host. See :ref:`licensing`. 

   .. code::

       license_ntls_server: 192.168.113.2:3133

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

   .. code::

       fetch:
         enabled: true
         size_limit: 10485760
   
#. The ``min_face_size`` and ``max_face_size`` parameters do not work as filters. They rather indicate the guaranteed detection interval. Pick up their values carefully as these parameters affect performance.

   .. code::
    
      nnd:
        min_face_size: 30
        max_face_size: .inf

#. The ``model_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. 

   .. important:
      For the GPU-based ``findface-extraction-api``, set ``model_instances: 1`` (optimal value). 

   .. code::

       model_instances: 2

#. To estimate the face quality, enable the ``quality_estimator``. In this case, ``extraction-api`` will return the quality score in the :ref:`detection_score <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.

   .. code::

       quality_estimator: true

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

   .. code::
      
      models:
        age: faceattr/age.v1.cpu.fnk
        emotions: faceattr/emotions.v1.cpu.fnk
        face: face/elderberry_576.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             | CPU          | ``face: face/elderberry_576.cpu.fnk``      |
   | (biometry)       +--------------+--------------------------------------------+
   |                  | GPU          | ``face: face/elderberry_576.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, simply 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. 

      .. code::

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


#. Enable the ``findface-extraction-api`` service autostart and launch the service.

   .. code::

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


.. _findface-tarantool-server:


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), while 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:

#. Install ``findface-tarantool-server``

   .. code::

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

#. Disable autostart and stop the Tarantool exemplary service.

   .. code::

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

#. Open the configuration file:

   .. code::

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

#. 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,

#. 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”})

#. By default, you can access Tarantool only from a 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”})

#. 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..``.

   .. code::

      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=576,                                                                                                                                                                                                                      
              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
                  },
                  }
          }
      )

#. (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 its physical processor cores minus 1. Bear it in mind, when designing your system architecture in a cluster environment. 

   To create multiple shards, simply multiply the configuration file for the default shard (``/etc/tarantool/instances.enabled/FindFace.lua``) overriding 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``.

   .. code::

      #!/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 :download:`exemplary script <_scripts/shard.sh>`.

   Run the script from the home directory.

   .. code::

      sudo sh ~/shard.sh

   Check the configuration files created.

   .. code::

       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 

#. Enable the ``findface-tarantool-server`` shard autostart and launch the shard. 

   .. code::

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

   .. code::

       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 (facens) in the Tarantool-powered biometric database.

Install ``findface-upload`` as such:

   .. code::

      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/``. 
   

.. _findface-sf-api:

Deploy ``findface-sf-api``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

#. Install ``findface-sf-api`` as such:

   .. code::

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

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

   .. code::

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

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

   .. code::

      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/

#. Enable the ``findface-sf-api`` service autostart and launch the service. 

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

.. _findface-upload:


.. _findface-facerouter:

Deploy ``findface-facerouter``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

#. Install ``findface-facerouter`` as such:

   .. code:: 

      sudo apt update
      sudo apt install -y findface-facerouter    

#. Open the ``/etc/findface-facerouter.py`` configuration file.

   .. code::

      sudo vi /etc/findface-facerouter.py

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

   .. code::

      sfapi_url                      = 'http://localhost:18411'

#. Enable the ``findface-facerouter`` service autostart and launch the service. 

   .. code::

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



.. _video-face-detection:


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:

#. Install ``findface-video-manager``:

   .. code::

      sudo apt install -y findface-video-manager

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

   .. code::

      sudo /etc/findface-video-manager.conf

#. 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``.

   .. code::

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

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

   .. code::

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

#. If necessary, configure the video processing settings which are applicable 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 :ref:`video-api`).

#. Enable the ``findface-video-manager`` service autostart and launch the service.

   .. code::

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

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

#. Install ``findface-video-worker``:

   .. code::

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

   .. 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 :ref:`video-cards`.

#. Open the ``/etc/findface-video-worker.ini`` (``/etc/findface-video-worker-gpu.ini``) configuration file.

   .. code::

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

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

   .. code::

      ntls-addr=127.0.0.1:3133

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

   .. code::

      mgr-static=127.0.0.1:18811

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

   .. code::

      capacity=10

#. Enable the ``findface-video-worker`` autostart and launch the service.

   .. code::
 
      sudo systemctl enable findface-video-worker.service && sudo systemctl start findface-video-worker.service

   .. note:
      The same commands for ``findface-video-worker-gpu`` are as such:

      .. code::

         sudo systemctl enable findface-video-worker-gpu
         sudo systemctl start findface-video-worker-gpu