Install on Linux

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 a form of Docker images. For a 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.

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

To install the SmartFace on the Docker environment, you need to match some general requirements and have your license ready. If you are not prepared yet, please return to the introduction to installation.

Video Tutorial

If you prefer a video step by step guide please watch the prepared tutorial video. If you prefer to read a step by step guide, please skip this section and navigate to the General requirements section.

General requirements

There are several requirements on an operation system and other software that are needed for successful installation of the 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
  • To have the Docker, Docker Compose and Docker CLI installed on your machine, Docker version 20.10.10 or higher and Docker Compose version 1.29.0 or higher. Generally, we recommend using the latest versions of the aforementioned software.

Download Installation Files

SmartFace Platform on Linux is distributed as a set of Docker images hosted on GitLab Container Registry and a 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 Customer Portal.

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), except the camera service, which will be spawned 5 times. By default, the script will deploy PostgreSQL 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. For such deployments you should consider proper architecture and scaling.

Docker Compose is not the only way 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 the 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 Microsoft 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.

Deployment of the SmartFace Platform

Download the required files using the GIT by running command below in the desired location:
git clone

Alternatively, you can download a zip archive file containing docker-compose files, scripts and configuration files from our public GitHub repository and unzip downloaded files into a desired location where you have necessary rights.

Within the file structure, there are several pre-sets, for the purpose of the first installation we will decide to go with the folder smartface/sf-docker/all-in-one representing the All In One preset.

Each pre-set has its own folder. For example for the LFIS preset - matching the Lightweight Facial Identification Service use case it is smartface/sf-docker/LFIS. For more information about existing presets please read the Deployment Pattern guide.

ℹ️ You can deploy and configure SmartFace Platform based on your needs and the use case for which SmartFace Platform will be used. The configuration can be applied in the provided docker-compose.yml, sf_dependencies/docker-compose.yml and the .env files. More information about the maintenance of the SmartFace Platform is available in the guides section.

It is not necessary but it is recommended to remove the need to use sudo within your docker installation as described in the docker documentation. You can do it easily by following the next few steps.

  1. Create the docker group: sudo groupadd docker

  2. Add your user to the docker group: sudo usermod -aG docker $USER

  3. Run the following command to activate the changes to groups:
    newgrp docker

If the recommended steps did not have the expected effect and you still need to use sudo before basically each docker action, try to log out and log back in so that your group membership is re-evaluated. If you’re running Linux in a virtual machine, it may be necessary to restart the virtual machine for changes to take effect.

Apply License

Copy the iengine.lic license file obtained in the Customer Portal to the smartface/sf-docker/all-in-one directory containing several files and subfolders, including the docker-compose file and script.

Run the SmartFace

To initiate the SmartFace you need to be logged into the You have done it while obtaining the hardware ID. Please redo the action if necessarry.

Ensure the file is executable.

Run the script via command: ./

This will deploy the SmartFace Platform with a default configuration. Once the script is successfully finished all the services will be up and running.

Validate your Installation

Once the services are up and running you can visit the port 8000 on your installation machine in your preferred browser. Such as the URL: http://localhost:8000

After the SmartFace Platform is installed, you can also view the status of the services running via docker command: docker ps -a. The services mentioned should be in the UP state. Please keep in mind this is not the final list and the list presented will differ based on your installation.

The results would be as below:

[user@smartface-server ~]$ sudo docker ps -a
CONTAINER ID   IMAGE                                                                                             COMMAND                  CREATED        STATUS                   PORTS                                                                                                                                                                                                                                       NAMES
9f9ea848768c                "dotnet SmartFace.St…"   7 days ago     Up 7 days                                                                                                                                                                                                                                                            SFStreamDataDbWorker
a23821079dec                           "dotnet RpcWatchlist…"   7 days ago     Up 7 days                                                                                                                                                                                                                                                            SFWatchlistMatcher
3e0be1015127                               "dotnet SmartFace.Ca…"   7 days ago     Up 7 days      >30000/tcp, :::30006->30000/tcp                                                                                                                                                                                               SFCam6
e3a8f6f428ab                               "dotnet SmartFace.Ca…"   7 days ago     Up 7 days      >30000/tcp, :::30010->30000/tcp                                                                                                                                                                                               SFCam10
358b1ab147ba                          "dotnet RpcLiveness.…"   7 days ago     Up 7 days                                                                                                                                                                                                                                                            smartface_liveness-gpu_1
14d95e1a5c55                              "dotnet SmartFace.dl…"   7 days ago     Up 7 days      >2406/tcp, :::2406->2406/tcp                                                                                                                                                                                                   SFBase
7cd2e038a1ec               "dotnet RpcPedestria…"   7 days ago     Up 7 days                                                                                                                                                                                                                                                            smartface_pedestrian-detector-gpu_1
77749795f8bb                               "dotnet SmartFace.Ca…"   7 days ago     Up 7 days      >30000/tcp, :::30002->30000/tcp                 

After Installation

Once your installation is done and your SmartFace is up and running, you can follow an additional tutorial guiding you through your first steps after installation of the SmartFace - registering a Watchlist Member, adding a camera and getting you first identification.