.. _update:

Upgrade FindFace Security to FindFace Multi
=============================================

If you are already using our product `FindFace Security <https://docs.findface.pro/projects/ffsecurity/en/4.5.0.1/>`__, you can upgrade it to FindFace Multi. 

.. important::
   Your current license will determine the scope of the features activated in FindFace Multi after the upgrade.

.. warning::
   When updating from FindFace Security 4.2 or earlier, be aware that :ref:`offline videos <offline-video>` will be lost and cannot be re-processed in FindFace Multi with different parameters. If you use this functionality, first delete the videos in the FindFace Security web interface. Then, after the system update, re-upload and re-process the videos that you want to keep in FindFace Multi. 

   If you don't do so, then after the update, you will still be able to see the video-related events but without association with the specific video.

   You can find the videos at ``/var/lib/findface-security/uploads/videos/`` (default path). The actual path to the directory is specified in the ``MEDIA_ROOT`` parameter in ``/etc/findface-security/conf.py``. We recommend you delete the videos if you no longer need them. 

To upgrade FindFace Security from any previous version to FindFace Multi, do the following:

#. Open the ``/etc/findface-security/config.py`` (``/etc/ffsecurity/config.py``) configuration file. Save the values of the following parameters for later use: ``EXTERNAL_ADDRESS``, ``SECRET_KEY``, ``VIDEO_DETECTOR_TOKEN``, ``ROUTER_URL``.

   .. code::

      # FindFace Security 4.2 and earlier     

      sudo vi /etc/ffsecurity/config.py

      # FindFace Security 4.3 and later 

      sudo vi /etc/findface-security/config.py

      EXTERNAL_ADDRESS = "http://172.20.77.58"

      ...
      # use pwgen -sncy 50 1|tr "'" "." to generate your own unique key
      SECRET_KEY = 'c8b533847bbf7142102de1349d33a1f6'

      FFSECURITY = {
         'VIDEO_DETECTOR_TOKEN': '381b0f4a20495227d04185ab02f5085f',
         ... 
         'ROUTER_URL': 'http://172.20.77.58',
         ...
      }
 
#. Stop the ``findface-security`` service.

   .. code::

      sudo systemctl stop findface-security*.service

#. Create a backup of the Tarantool-based feature vector database in any directory of your choice, for example, ``/etc/findface_dump``. 

   .. tip::
      See :ref:`backup-restore` for details.
 
   .. code::

      sudo mkdir -p /etc/findface_dump
      cd /etc/findface_dump
      sudo findface-storage-api-dump -config /etc/findface-sf-api.ini


#. Install the apt repository with FindFace Multi, using the console installer as described in :ref:`this section <install-repo>`.

#. If you are upgrading from FindFace Security version 4.1.2 or earlier, do the following:

   #. Give a strong password to the ``ntech`` user (``9T3g1nXy9yx3y8MIGm9fbef3dia8UTc3`` in the example below). Output the credentials to the ``pgbouncer`` user list.

      .. code:: 

         echo '"ntech" "9T3g1nXy9yx3y8MIGm9fbef3dia8UTc3"' | sudo tee -a /etc/pgbouncer/userlist.txt 

   #. Install the ``pgbouncer`` package as such:

      .. code::

         sudo apt update
         sudo apt install -y pgbouncer

   #. Configure ``pgbouncer``. In ``/etc/pgbouncer/pgbouncer.ini``, add ``ffsecurity`` to the ``databases`` section. Configure named parameters, as shown in the example below. Parameters other than those must be commented out.

      .. code::

         sudo vi /etc/pgbouncer/pgbouncer.ini

         [databases]
         ffsecurity = dbname=ffsecurity host=localhost port=5432 user=ntech
         [pgbouncer]
         pidfile = /var/run/postgresql/pgbouncer.pid
         listen_addr = 127.0.0.1
         listen_port = 5439
         unix_socket_dir = /var/run/postgresql
         auth_type = plain
         auth_file = /etc/pgbouncer/userlist.txt
         pool_mode = transaction
         server_reset_query = DISCARD ALL
         max_client_conn = 16384
         default_pool_size = 20
         syslog = 1

   #. Copy the password of the ``ntech`` user (``9T3g1nXy9yx3y8MIGm9fbef3dia8UTc3`` in the example). In :program:`PostgreSQL`, set the copied password for the ``ntech`` role. Open the :program:`PostgreSQL` interactive terminal. You will see the line ``postgres=#`` appear. After the ``#`` sign, enter the following command: ``ALTER ROLE ntech PASSWORD '<copied password>'``.

      .. code::

         sudo -u postgres psql

         postgres=# ALTER ROLE ntech PASSWORD '9T3g1nXy9yx3y8MIGm9fbef3dia8UTc3';

   #. Using the :program:`PostgreSQL` interactive terminal, create a database ``ffcounter`` in PostgreSQL. 

      .. code::

         postgres=# CREATE DATABASE ffcounter WITH OWNER ntech ENCODING 'UTF-8' LC_COLLATE='C.UTF-8' LC_CTYPE='C.UTF-8' TEMPLATE template0;


   #. Restart :program:`PostgreSQL`.

      .. code::

         sudo systemctl restart postgresql@10-main.service

   #. Create and configure ``pgbouncer.service``.

      .. code::

         sudo touch /etc/systemd/system/pgbouncer.service
         sudo vi /etc/systemd/system/pgbouncer.service

      Insert the following code:

      .. code::

         [Unit]
         Description=Pgbouncer service
         After=postgresql.service
         Before=findface-security.service
         [Service]
         User=postgres
         Group=postgres
         ExecStart=/usr/sbin/pgbouncer "/etc/pgbouncer/pgbouncer.ini"
         [Install]
         WantedBy=multi-user.target

   #. Enable the ``pgbouncer.service`` autostart and restart it:

      .. code::

         sudo systemctl enable pgbouncer.service
         sudo systemctl restart pgbouncer.service

#. Install the FindFace Multi services from the repository, following your architecture outline.

   CPU-version:
 
   .. code::

      sudo apt update
      sudo apt install findface-security findface-security-ui findface-extraction-api findface-ntls findface-sf-api findface-tarantool-server findface-upload findface-video-manager findface-video-worker-cpu findface-counter findface-liveness-api

   GPU-version:

   .. code::

      sudo apt update
      sudo apt install findface-security findface-security-ui findface-extraction-api-gpu findface-ntls findface-sf-api findface-tarantool-server findface-upload findface-video-manager findface-video-worker-gpu findface-counter findface-liveness-api

   .. important::
      FindFace Multi on GPU requires the prior installation of :ref:`NVIDIA drivers <nvidia-drivers>`.

   .. important::
      At some moment, you will be prompted to choose which version of the ``findface-security`` configuration file to keep. Opt for ``Install the packages maintainer’s version``.


#. Enable the ``findface-counter`` and ``findface-liveness-api`` services autostart.

   .. code::

      sudo systemctl enable findface-counter.service findface-liveness-api.service


#. Open the ``/etc/findface-security/config.py`` configuration file and paste the saved ``EXTERNAL_ADDRESS``, ``SECRET_KEY``, ``VIDEO_DETECTOR_TOKEN``, and ``ROUTER_URL`` into it. Fill in the ``DATABASES`` section by analogy: ``'PORT': 5439, 'USER': 'ntech', 'PASSWORD': '9T3g1nXy9yx3y8MIGm9fbef3dia8UTc3'`` (password from ``/etc/pgbouncer/userlist.txt``).

   .. code::

      sudo vi /etc/findface-security/config.py
      ...
      # Database is used by FindFace Security to store cameras,
      # camera groups, watchlists and so on. Only PostgreSQL is supported.
      DATABASES = {
          'default': {
              'ENGINE': 'django.db.backends.postgresql',
              'DISABLE_SERVER_SIDE_CURSORS': True,
              'NAME': 'ffsecurity',
              'PORT': 5439, 'USER': 'ntech', 'PASSWORD': '9T3g1nXy9yx3y8MIGm9fbef3dia8UTc3',
          }
      }
      ...
      # Use pwgen -sncy 50 1|tr "'" "." to generate your own unique key
      SECRET_KEY = '002231ccb690586f4d33e98322c591bb'
      ...
      SERVICE_EXTERNAL_ADDRESS = 'http://172.20.77.58'
      # EXTERNAL_ADDRESS is used to access objects created inside FFSecurity via external links.
      EXTERNAL_ADDRESS = 'http://172.20.77.58'
      ...
          # findface-video-worker authorization token
          'VIDEO_DETECTOR_TOKEN': '8977e1b0067d43f6c908d0bf60363255',
      ...
          # findface-video-worker face posting address,
          # it must be set to either FFSecurity EXTERNAL_ADDRESS (by default)
          # or findface-facerouter url (in some specific cases)
          'ROUTER_URL': 'http://127.0.0.1:80',

#. Open the old version of the ``findface-ntls`` configuration file available at ``/etc/findface-ntls.cfg.dpkg-old`` and check it against the new version ``/etc/findface-ntls.cfg``. Make sure that all the custom parameters from the old version are present in the new one. Do the same for other components, e.g. for ``findface-extraction-api``, check ``/etc/findface-extraction-api.ini.ucf-old`` against ``/etc/findface-extraction-api.ini``, etc. 

   .. code::

      sudo vi /etc/findface-ntls.cfg.dpkg-old
      sudo vi /etc/findface-ntls.cfg
      sudo vi /etc/findface-extraction-api.ini.ucf-old
      sudo vi /etc/findface-extraction-api.ini

      ...


#. Restart the services.

   .. code::

      sudo systemctl restart findface-ntls findface-extraction-api findface-video-worker* findface-video-manager findface-sf-api findface-counter findface-liveness-api


#. Modify the Tarantool database structure by applying the ``tnt_schema.lua`` file from FindFace Multi.
 
   .. code::

      sudo findface-security make_tnt_schema | sudo tee /etc/findface-security/tnt_schema.lua

#. Stop the ``findface-tarantool-server`` shards. Purge data from all the directories relevant to active shards.
 
   .. code::

      sudo systemctl stop 'tarantool@*'

      sudo rm /opt/ntech/var/lib/tarantool/shard-*/{index,snapshots,xlogs}/*

#. Navigate to the directory with Tarantool configuration file(s) ``/etc/tarantool/instances.available/``. Check whether each configuration file ``shard-*.lua`` contains the ``dofile`` command, ``meta_indexes`` and ``meta_scheme`` definitions, as in the example below.  

   .. code::

      sudo vi /etc/tarantool/instances.available/shard-*.lua
 
      ...
      dofile("/etc/findface-security/tnt_schema.lua")
      ...
      FindFace.start("127.0.0.1", 8101, {
          license_ntls_server="127.0.0.1:3133",
          meta_indexes=meta_indexes,
          meta_scheme = meta_scheme
      })

#. Restart the ``findface-tarantool-server`` shards.

   .. code::

      TNT=$(ls /etc/tarantool/instances.enabled/ | cut -c 7,8,9)
      for i in $TNT; do sudo systemctl restart tarantool@shard-$i.service ; done


#. Restore the Tarantool database from the backup.
 
   .. code::

      cd /etc/findface_dump

      for x in *.json; do sudo findface-storage-api-restore -config /etc/findface-sf-api.ini < "$x"; done

#. Migrate the old data from the ``v2`` to ``v3`` API version of the ``findface-sf-api`` service.

   .. code::

      sudo findface-sf-api-migrate-v2-v3 -config /etc/findface-sf-api.ini

#. Migrate the main database architecture from FindFace Multi to :program:`PostgreSQL`, re-create user groups with :ref:`predefined <users>` rights, and the first user with administrator rights.

   .. code::

      sudo findface-security migrate
      sudo findface-security create_groups
      sudo findface-security create_default_user

#. Restart the ``findface-security`` service.

   .. code::

      sudo systemctl restart findface-security.service


.. important::

   To preserve the FindFace Multi compatibility with the installation environment, we highly recommend you to disable the Ubuntu automatic update. In this case, you will be able to update your OS manually, fully controlling which packages to update.

   To disable the Ubuntu automatic update, execute the following commands:

   .. code::

      sudo apt-get remove unattended-upgrades
      sudo systemctl stop apt-daily.timer
      sudo systemctl disable apt-daily.timer
      sudo systemctl disable apt-daily.service
      sudo systemctl daemon-reload