This documentation guides you through the installation process of SmartFace prerequisites and SmartFace Platform on Linux OS using docker images. SmartFace Platform for Linux is distributed in form of docker images. For successful installation it is required that you have an admin level experience with Linux OS and minimal basic knowledge of docker technology - understanding docker images, docker compose, docker container and docker registry.

Prerequisites

There are several requirements on an operation system and other software that is needed for successful installation of SmartFace Platform on Linux.

SmartFace version 4.10 and higher versions require the CPU support AVX2 instruction set , eg Intel Haswell microarchitecture or AMD Zen family

Required Linux OS distribution

Distributed docker images of SmartFace Platform requires Docker engine with Linux containers. The deployment is limited only to Linux platforms that are supported by Docker technology. For more information see Docker Install documentation.

Required Docker and Docker Compose

It is required that you have Docker engine and Docker CLI installed on your machine. SmartFace Platform requires Docker version 20.10.0 and higher.

In case you want to perform default deployment, it is required that you have Docker Compose installed on your machine. SmartFace Platform requires Docker Compose version 1.29.0 and higher.

SmartFace Platform distribution for Linux

SmartFace Platform on Linux is distributed as a set of Docker images hosted on GitLab Container Registry and zip archive with a docker-compose files, scripts and configuration files hosted on GitHub. To pull (download) the docker images you will need credentials (name and password) available on our CRM.

In case you would like to perform basic deployment and install SmartFace Platform as fast as possible with a default configuration, ie. do not want to perform custom large deployment, for example on multiple servers, you can use provided scripts. Provided docker-compose files and scripts will deploy one instance of every service (container), expect camera service, which will be spawned 5 times. By default, the script will deploy MS SQL database and SmartFace Platform will be configured to process only on CPU. Scripts will also use Docker Compose orchestration engine. This kind of deployment can be used for demonstration and presentation purposes. It is not aimed for large production deployments.

Docker Compose is only a one way how to orchestrate SmartFace Platform containers. You can find more information about the Docker Compose here. Docker Compose is used as an orchestration engine because it is simple and easy to use. There are more robust orchestration engines for production workloads available, such as Kubernetes, Nomad or Docker Swarm. It is up to you which engine you will use for a deployment of SmartFace Platform docker images.

In case you would like to perform custom or large deployment of SmartFace Platform, eg. spawn more instances of respective services, deploy Postgre SQL database instead of MS SQL, use different orchestration engine, or do any other custom change, you can use provided docker-compose files and scripts and change them to your need and to your use case for which SmartFace Platform will be used.

You can deploy and configure SmartFace Platform based on your needs and use case for which SmartFace Platform will be used. The configuration can be applied in provided docker-compose.yml, sf_dependencies/docker-compose.yml and .env files.

images/download/attachments/124096690/01_Installation_-_SmartFace_on_Linux_Installation.svg

Obtain the SmartFace license

To obtain your license please follow these steps:

Login to container registry on your device (the credentials are available in our CRM portal):

docker login registry.gitlab.com -u <username> -p <password>
Identify hardware ID (HWID) for your machine with command

docker run registry.gitlab.com/innovatrics/smartface/license-manager:3.2.7

This process work for native Linux. For WSL2 (e.g. Linux containers on Windows) you need a special license for which you need to contact our sales.
Obtain the license for your HWID from our CRM portal for product SmartFace
Download the license file iengine.lic

Deployment of SmartFace Platform

Before you start the deployment you need to manually perform following steps:

Download zip archive file containing docker-compose files, scripts and configuration files from our public GitHub repository.
Unzip downloaded files.
Copy the iengine.lic license file to the directory with docker-compose file and scripts where run.sh script is located.
Login to the container registry using the provided credentials.
1. Run command: docker login registry.gitlab.com
2. Enter provided credentials

Now you can run the run.sh script deploying SmartFace Platform with a default configuration. Once the script is successfully finished all the services should be up and running.

Steps performed by the run.sh script

When you run the script on a machine with an empty docker engine (no previous images/containers), the script performs following steps:

Checks the presence of iengile.lic file. If not present, the script ends.
Creates a docker network called sf-network. This docker network is used by all other containers created by this script and enables containers to communicate with each other.
Sets up services from sf_dependencies that SmartFace Platform needs to run properly. Docker will check the presence of these images on local docker host. In case the images are not present, images are pulled from the container registry. The download can take up to several minutes.
Docker spawns containers from prerequisites images, for example:
1. MSSQL/PGSQL database
2. RabbitMQ
3. Minio NoSQL database
Parses SmartFace Version and registry information from .env file.
Creates MSSQL database named "SmartFace".
Uses sf-admin image to perform database migration - creates required table structure and seeding the database. The image is pulled from the container registry if it is not present on the machine. This step will fail if the docker login was not performed correctly and script ends.
Executes the SmartFace Platform Docker Compose file. This results in SmartFace Platform services to be up and running on the machine. The execution does the following
1. Pulls SmartFace Platform images from container registry. The download can take up to several minutes.
2. Builds new SmartFace Platform images that will contain the provided license file. This is done using the license.Dockerfile which just adds a new layer containing the license file to an arbitrary existing image. This step can be replaced by mounting the license file to the containers.
3. Spawns containers from images, for example:
  1. camera service
  2. detector service
  3. extractor service
4. Uses the values from .env file to properly configure SmartFace Platform containers so everything works properly. To use this file to configure SmartFace Platform for different deployment than described here see docker documentation.

When the script finishes, SmartFace will be available to use on the local machine with all services up and running.

Uninstallation of SmartFace Platform on Linux

In case you would like to uninstall SmartFace Platform, you can simply delete created containers and other data in the Docker. To do so , follow these steps:

Stop Docker Compose for SmartFace Platform containers by running this command in the main directory where docker-compose file is located:
docker-compose down
Stop Docker Compose for prerequisites containers by running this command in sf_dependencies directory where docker-compose file for prerequisites is located:
docker-compose down
Remove and delete SmartFace data, docker containers, volumes, networks and images by running this command:
docker system prune -af --volumes

Please consider backing up your data before uninstalling SmartFace Platform from your machine. Deleting data with the prune command will remove all of the stopped containers as well as all downloaded images and configuration.