.. _distributed-dossiers:

Distributed Dossier Database
======================================================

In a distributed architecture, it is often necessary to have the dossier database distributed among several hosts. 

In the current implementation, the dossier database is available for editing only on the principal server known as ``master``. It is in sync with several additional FindFace Security instances that serve as ``slaves``. On the slaves, the dossier database is available only for reading and monitoring.

.. important::
   You will be able to delete dossiers on the slaves if the master is unavailable.  

.. important::

   If a watch list on the future slave already contains dossiers, they will be replaced with those from the master during the first synchronization. All information in the previous dossiers will be lost. 

.. warning::
   Neural networks on the master and slaves must be identical. 



.. rubric:: In this section:

.. contents::
   :local:
 
Configure Master/Slave Synchronization
-----------------------------------------------
 
To configure master/slave synchronization, do the following:

#. On the master, open the ``findface-security`` configuration file. Come up with a synchronization token and specify it in the ``SYNC_TOKEN`` parameter (be sure to uncomment it prior). 

   .. code::

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

      # ========== DossierLists sync ===========
      ...
      # token must be identical on master and slave
      # use pwgen -s 64 1
      SYNC_TOKEN = 'ABC_123456789'
      ...

#. Copy the synchronization token into the ``findface-security`` configuration file on the slave(s).
#. Make sure that the ``EXTERNAL_ADDRESS`` parameter of the ``findface-security`` configuration file on the slave(s) contains the same address as on the master.

The master/slave sync is now set and will be enabled once you configure a watch list replication from the master to slave(s).


Replicate Watch List from Master to Slaves
-------------------------------------------------------

To replicate a watch list from the master to slave instances, send a POST request to the slave with the following parameters in the body:

* ``remote_dossier_list``: id of the original watch list on the master
* ``remote_url``: master URL
* ``slave_dossier_list``: id of the watch list on the slave, which is to be a replica of the original watch list

.. code::

   POST /sync/dossier-lists/
   {remote_dossier_list: 1,
   remote_url: "http://172.17.46.14",
   slave_dossier_list: 3}

  
Set Synchronization Time
-------------------------------

By default, replicated watch lists on the slaves and the master are synced nightly at 3 a.m. You can modify the synchronization time as follows:

#. Open the ``findface-security`` configuration file on the master.

   .. code::

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

#. Uncomment the following lines and set your own schedule.

   .. code::

      ...

      # ========== DossierLists sync ===========
      ...
      SYNC_TIME = {
          # 24 hour format
          'hour': 3,
          'minute': 0,
      }


Cancel Watch List Replication and Synchronization
-----------------------------------------------------

To cancel a watch list replication and synchronization, send the following API request to the slave with the ``{id}`` of the watch list on the slave:

.. code::

   DELETE /sync/dossier-lists/{id}/


Duplicate Functionality to Web Interface
----------------------------------------------

By default, you can enable and disable watch list replication only via API. To make the functionality available in the web interface as well, do the following:

#. Open the ``findface-security`` configuration file on the master.

   .. code::

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

#. Enable the ``ffsecurity_sync`` plugin by uncommenting the line ``INSTALLED_APPS.append('ffsecurity_sync')`` into the plugins section:

   .. code::

      ...

      # ========== DossierLists sync ===========
      INSTALLED_APPS.append('ffsecurity_sync')
      ...

#. Do the same on each slave.
#. On each host, migrate the main database architecture from FindFace Security to :program:`PostgreSQL`. Re-create user groups in the main database. Restart the ``findface-security`` service. 

   .. code::

      sudo findface-security migrate
      sudo findface-security create_groups
      sudo systemctl restart findface-security.service