.. _docker-commands:

Post-deployment Procedures and How-to's
---------------------------------------------------------------

After you are finished with the FindFace Multi deployment, perform the procedures below.

.. rubric:: In this section:

.. contents::
   :local:


Specify Time Zone
^^^^^^^^^^^^^^^^^^^^^^

The time zone on the FindFace Multi server determines the time in reports, logs, and names of such FindFace Multi artifacts as detection full frames and thumbnails, etc.

The time zone is specified in the ``/opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py`` configuration file, either in the ``Region/Country/City`` or ``Etc/GMT+H`` / ``Etc/GMT-H`` format.

.. code::

   sudo vi /opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py

   # time zone
   TIME_ZONE = 'America/Argentina/Buenos_Aires'

.. note::

    The preferred way to refer to a time zone is by a location, e.g., ``Europe/Moscow``, ``America/Los_Angeles``. The best way is to copy/paste your time zone from `this table <https://en.wikipedia.org/wiki/List_of_tz_database_time_zones>`_ on Wikipedia.

    The ``GMT+X`` format means that the time is ahead of UTC (for example, ``GMT+3 = Moscow``).
    Time zones of the form ``Etc/GMT+n`` and ``Etc/GMT-n`` assume offset from UTC (hence no DST) and have an inverted sign. Negative offsets are times ahead of (East of) UTC, positive offsets are times behind (West of) UTC.

    * ``Etc/GMT+3 = UTC-3`` (Rio de Janeiro, Buenos Aires).
    * ``Etc/GMT-3 = UTC+3`` (Moscow, Istanbul (winter)).

Restart all FindFace Multi containers.

.. code::

   cd /opt/findface-multi/

   sudo docker-compose restart


License Instance
^^^^^^^^^^^^^^^^^^^^^^

FindFace Multi provides several licensing options. Whichever option you choose, you upload the FindFace Multi license file via the main web interface ``http://<Host_IP_address>/#/license``. To access the web interface, use the ``superuser`` credentials.

.. important::
   Do not disclose the ``superuser`` (Super Administrator) credentials to others. To administer the system, create a new user with administrator privileges. Whatever the role, the Super Administrator cannot be deprived of its rights.

Refer to the :ref:`licensing-principles` section to learn about the licensing options available.

Configure Logging
^^^^^^^^^^^^^^^^^^^^

By default, the FindFace Multi processes are logged to `Docker container logs <https://docs.docker.com/config/containers/logging/>`__,  which can be accessed via the ``docker logs`` and ``docker service logs`` commands. In addition, Docker uses the `json-file logging driver <https://docs.docker.com/config/containers/logging/json-file/>`__, which caches container logs in JSON.  You can configure Docker to use another logging driver, choosing from the `multiple logging mechanisms available <https://docs.docker.com/config/containers/logging/configure/>`__. See :ref:`logs` to learn how to do it.

.. _useful-docker-commands:

Useful Docker Commands
^^^^^^^^^^^^^^^^^^^^^^^^^

In order to efficiently and easily administer FindFace Multi, a solid understanding of Docker and its related tools is required. If you're new to Docker, explore the `Docker documentation <https://docs.docker.com/>`__. The Docker commands that you may find useful while working with FindFace Multi are listed below.

* View all Docker containers, including the stopped ones:

  .. code::

     docker ps -a

  To get a more compact and understandable output, execute:

  .. code::

     docker ps -a --format "table {{.ID}}\t{{.Names}}\t{{.Status}}\t{{.State}}"

  To extend the previous output, execute:

  .. code::

     docker ps --format='{{json .}}' | jq

* List all networks:

  .. code::

     docker network ls

* Restart the Docker service:

  .. code::

     sudo systemctl restart docker

* View a container log. With the ``-f`` option (an alias for the ``--follow`` option) will print the current log and continue streaming new messages in real time:

  .. code::

     sudo docker logs <container_name>/<container_id> -f   

* View a container log if the ``journald`` logging driver is :ref:`enabled <logs>`:

  .. code::

     journalctl CONTAINER_NAME=findface-multi-findface-multi-legacy-1 -f
     
* Stop a Docker container:

  .. code::

     sudo docker stop <container_name>/<container_id>

  Stop all Docker containers:

  .. code::

     sudo docker stop $(sudo docker ps -a -q)

* Start a Docker container:

  .. code::

     sudo docker start <container_name>/<container_id>

  Start all Docker containers:

  .. code::

     sudo docker start $(sudo docker ps -a -q)

* The FindFace Multi ``docker-compose.yaml`` file can be viewed as such:

  .. code::

     cat /opt/findface-multi/docker-compose.yaml

* FindFace Multi configuration files can be found here:

  .. code::

      cd /opt/findface-multi/configs/

  Once you made changes to a configuration file, restart a relevant container by executing:

  .. code::

     sudo docker restart <container_name>/<container_id>

* Enter a running Docker container to execute a command in it:

  .. code::

     sudo docker exec -it <container_name> /bin/bash

* Stop and remove all FindFace Multi containers:

  .. code::

     cd /opt/findface-multi
     sudo docker-compose down

* Build, recreate, and start FindFace Multi containers in the background and leave them running:

  .. code::

     cd /opt/findface-multi
     sudo docker-compose up -d

  Executing the ``docker-compose up`` command without any options will aggregate logs for each container until you pause the process. In this documentation, we will use the ``docker-compose up`` command with the ``-d`` option (an alias for the ``--detach`` option) as a preferable way to start FindFace Multi containers.

To display help on any command, execute the command with the ``--help`` option.

.. code::

   docker <command> --help

Explore the `official Docker CLI reference <https://docs.docker.com/reference/cli/docker/>`__ for detailed information on Docker commands.