SmartFace
How to update Smartface
To update your SmartFace to a newer version, please visit the releases to find out what version is the latest. In the case you have an older version that you would like to update to the latest, please apply changes as described in the UPGRADES section of the left menu, one step at a time, starting from your current version.
For the Docker version, it is also possible to download the latest setup from our github, however in that case you might want to address your project specific differences in the newly aquired setup. Once you have applied your differences (camera numbers, camera configuration, service scaling, environment variables etc.), please run the “run.sh” script in the project folder. The script will migrate your current data into the latest format and will apply all the migration steps.
It is recommended to keep the SmartFace updated to the latest version. Please note that since the SmartFace version 5.4.20 released on 7th of July 2023 a new license format is used. If you would like to migrate from an older version than that into a newer version, please visit out Customer Portal for a new license.
Maintenance for Windows
This section is Windows specific
To effectively alter the running installation of the SmartFace Platform on Windows, you can use your favourite text editor to do changes in several files, including appsettings.json files SmartFace services. You can also do changes to the system via PowerShell Commands.
Controlling the Services
To use below mentioned commands, please open the PowerShell window in the Administration mode.
Get SmartFace services
You can get a list of existing SmartFace services by the command below:Get-Service -Name "SF*"
Stop SmartFace services
You can stop all SmartFace Platform services by the command below:Get-Service -Name "SF*" | Stop-Service
Remove all SmartFace services
You can remove all SmartFace Platform services by the command below:
Get-Service -Name "SF*" | foreach {sc.exe delete $_.Name}
Disable auto-start on all SmartFace services
You can disable auto-start of all SmartFace Platform services by the command below:Get-Service -Name "SF*" | foreach {sc.exe config $_.Name start= disabled}
Start all SmartFace services
You can start all the SmartFace Platform services by the command below:Get-Service -Name "SF*" | foreach {sc.exe start $_.Name}
Updating appsettings.json files
To make changes to a service configuration, please locate your SmartFace Platform installation path, per default: C:\Program Files\Innovatrics\SmartFace. Services have their own configuration files called *.appsettings.json. As the name suggest it stored configuration in the JSON format. You can do the changes using your favourite text editor. To apply a change, please restart the service.
Services have their own appsettings.json files
Maintenance for Docker
This section is Docker specific
To effectively alter the running installation of the SmartFace Platform on Linux using Docker, we can update several files and have options for several terminal commands. The changes can be done using your favourite text editor.
Controlling the services
To use the below mentioned commands, please use the Terminal or other Linux shell application.
To see all the docker containers running
This shows you all the containers from across docker and their status
sudo docker ps -a
To see only docker containers running from one specific docker-compose.yml file
Please enter the parent folder for the file, then run the command
sudo docker compose ps
To stop docker containers from one specific docker-compose.yml
Please enter the parent folder for the file, then run the command
sudo docker compose stop
To remove docker containers from one specific docker-compose.yml
Please enter the parent folder for the file, then run the command
sudo docker compose rm
To restart a specific container
This way you can restart one container at a time. This can help you to reload frozen service or apply changes to it’s configuration
sudo docker restart <name-of-the-container>
To start docker containers from one specific docker-compose.yml
Please enter the parent folder for the file, then run the command
sudo docker compose up -d
To stop and remove all docker containers
This will identify and stop and then remove all the containers that are running from across the docker
sudo docker stop $(docker ps -a -q)
sudo docker rm $(docker ps -a -q)
Updating SmartFace
To make changes to SmartFace, including the updates, you can update it’s services configuration and the Environment Variables. You can do the changes directly for each service configuration in the docker-compose.yml file, or you can do the changes in .env files. These are created specifically for several services to allows you to keep configuration separated from the architecture defined in the docker-compose.yml files.
It is possible you update several configuration files at once to propagate the expected changes. You can update the files using your favourite text editor. Each file can be updated separately and will apply changes only to services defined in or configured in the particular file. Even in a preset folder (Deployment Pattern) you will have more than one docker-compose.yml file. One is for the SmartFace Platform services, the other one is in the sf_dependencies subfolder to control and provide the SmartFace PreRequisities.
Updating Environment Variables
Instead of doing changes directly to each service configuration in the used docker-compose.yml file, or you can do the changes in .env files referenced by a service. This allows you to keep configuration separated from the architecture defined in the docker-compose.yml files.
There are several .env files for the common services. The list of .env files changes in time as more services are used.
.env
This file is used for general SmartFace Platform configuration. This includes RabbitMQ connection values, MQTT connection vales, database configuration, s3 storage configuration, gstreamer configuration and the versions to be used across SmartFace. For information about how to update SmartFace please look here.
.env.sfac
This file is used for configuration of the Access Controller module. For more information about the module and it’s configuration, please look here.
.env.sfstation
This file is used for configuration of the SmartFace Station. For more information about how to setup the SmartFace Station please look here.
.env.fa
This file is used for configuration of the Fingera Module. For more information about how to setup the Fingera Adapter, please look here.
.env.rc
This file is used for configuration of the Relay Connector module. For more information about how to setup the Relay Connector, please look here.
Applying changes
Once the changes are done to apply them you need to use one of the commands below:
- if there are just minor changes please use
docker compose up -d - if you have removed some of the services it is recommended to use the command to remove the unused (orphan services)
docker compose up -d --remove-orphans - if the changes are complex enought that the simple up command does not propagate all the changes, you can use
docker compose up -d --force-recreatecommand to ensure that any modifications are applied and that the containers are rebuilt from scratch
To see what containers are up and running, please use the command docker ps -a.
To see what containers are up and running based on the docker-compose.yml in the same folder you are presently located at, please use the command docker compose ps. You will see results such as:
user@smartface-server:/srv/smartface/sf-docker/all-in-one$ docker-compose ps
Name Command State Ports
----------------------------------------------------------------------------------------------------------------------------
53b4d78e-323f-4a0f-aa6d-99c464448b6d dotnet SmartFace.Camera.dl ... Up
SFAccessController dotnet SmartFace.AccessCon ... Up 0.0.0.0:5050->80/tcp,:::5050->80/tcp
SFApi dotnet SmartFace.Api.dll Up 0.0.0.0:8098->80/tcp,:::8098->80/tcp
SFBase dotnet SmartFace.dll --ser ... Up 0.0.0.0:2406->2406/tcp,:::2406->2406/tcp
SFBodyPartsDetectCpu dotnet RpcBodyPartsDetecto ... Up
SFCam1 dotnet SmartFace.Camera.dl ... Up 0.0.0.0:30001->30000/tcp,:::30001->30000/tcp
SFCam2 dotnet SmartFace.Camera.dl ... Up 0.0.0.0:30002->30000/tcp,:::30002->30000/tcp
SFCam3 dotnet SmartFace.Camera.dl ... Up 0.0.0.0:30003->30000/tcp,:::30003->30000/tcp
SFCam4 dotnet SmartFace.Camera.dl ... Up 0.0.0.0:30004->30000/tcp,:::30004->30000/tcp
SFCam5 dotnet SmartFace.Camera.dl ... Up 0.0.0.0:30005->30000/tcp,:::30005->30000/tcp
SFDetectCpu dotnet RpcDetector.dll Up
SFEdgeStreamProcessor dotnet SmartFace.EdgeStrea ... Up
SFExtractCpu dotnet RpcExtractor.dll Up
SFFaceMatcher dotnet RpcFaceMatcher.dll Up
SFGraphQLApi dotnet SmartFace.GraphQLAp ... Up 0.0.0.0:8097->80/tcp,:::8097->80/tcp
SFGroup dotnet SmartFace.Grouping. ... Up
SFLiveness dotnet RpcLiveness.dll Up
SFODataApi dotnet SmartFace.ODataApi.dll Up 0.0.0.0:8099->80/tcp,:::8099->80/tcp
SFObjectDetectorCpu dotnet RpcObjectDetector.dll Up
SFPedestrianDetectCpu dotnet RpcPedestrianDetect ... Up
SFPedestrianExtractorCpu dotnet RpcPedestrianExtrac ... Up
SFStation docker-entrypoint.sh node ... Up 0.0.0.0:8000->8000/tcp,:::8000->8000/tcp
SFStreamDataDbWorker dotnet SmartFace.StreamDat ... Up
SFVideoDataAggregator dotnet VideoDataAggregator.dll Up
SFVideoDataCollector dotnet VideoDataCollector.dll Up
SFVideoReader dotnet VideoReader.dll Up
SFWatchlistMatcher dotnet RpcWatchlistMatcher.dll Up
The list of services running might not match your setup. Please note the state mentioned. Expected state is Up, otherwise something went wrong.
Monitoring SmartFace
This section is Docker specific
The SmartFace Installation can be monitored in via several ways:
- metrics
- tracing
- reading logs
Metrics
The most of the services propagate their metrics, than can be read and observed and used as a trigger to a further maintenance event.
To use the metrics, you can:
- read metrics of services directly
- use an automatized observability system
Reading Metrics Manually
The services that provide metrics provide them on port 4318 in the docker installations. To read them manually you need to adjust your docker-compose.yml file for such services to propagate the metrics outside. Each service should provide a standalone port for it’s metrics, so it is reachable from the outside.
For the example below, the inner port 4318 was propagated outside of the container using port 4323. Another camera, such as camera sf-cam-4 can use another port, such as 4324.
sf-cam-3:
image: ${REGISTRY}sf-cam:${SF_VERSION}
container_name: SFCam3
command: --serviceName SFCam3
ports:
- 30003:${CameraDefaults__PreviewPort}
- 4323:4318
restart: unless-stopped
Once the port is propagated and the changes are applied, you can visit your camera’s metrics at the metrics endpoint at your service’s port.
An example URL:
http://localhost:4323/metrics
Tracing
The SmartFace Platform does provide tracing, allowing you to trace events and steps being performed during platform processes. This includes API calls, such as the REST API calls. Jaeger is being used as the tracing engine. By default it is turned off. To turn it on you need to edit .env configuration file and set the AppSettings__USE_JAEGER_APP_SETTINGS variable to true.
Once the .env configuration is updated you need to apply changes. Once the Jaeger tracing is allowed you can visit the web interface on the port 16686 (such as on the URL http://localhost:16686.
On the main page of the web interface you can use the Search function to find tracings you are interested in.
Search in tracing
Once you find a tracing you are interested in you can click on the tracing to get more information.
Search results
More detailed information is provided including each step and how long it takes to perform the step.
Detailed information
More information about Jaeger tracing can be found at https://www.jaegertracing.io/
Log files
Reading Log files
Each container creates its own logs during its lifetime. You can access them in real time if needed. To do so you need to know the name of the container you are after.
To find out the list of containers and their names you can use this command:
sudo docker ps -a
You get such result as below:
user@password:/srv/smartface $ docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS
87518ea0f03e registry.gitlab.com/innovatrics/smartface/sf-api:v5_4.22.0 "dotnet SmartFace.Ap…" 3 hours ago Up 3 hours 0.0.0.0:8098->80/tcp, :::8098->80/tcp SFApi
d5fbc111d7ab registry.gitlab.com/innovatrics/smartface/sf-cam:v5_4.22.0 "dotnet SmartFace.Ca…" 3 hours ago Up 3 hours 0.0.0.0:30003->30000/tcp, :::30003->30000/tcp SFCam3
d7542eb5bbb2 registry.gitlab.com/innovatrics/smartface/sf-graphql-api:v5_4.22.0 "dotnet SmartFace.Gr…" 3 hours ago Up 3 hours 0.0.0.0:8097->80/tcp, :::8097->80/tcp SFGraphQLApi
73a474ba1a76 registry.gitlab.com/innovatrics/smartface/sf-base:v5_4.22.0 "dotnet SmartFace.dl…" 3 hours ago Up 3 hours 0.0.0.0:2406->2406/tcp, :::2406->2406/tcp SFBase
b96c758a4c45 registry.gitlab.com/innovatrics/smartface/sf-cam:v5_4.22.0 "dotnet SmartFace.Ca…" 3 hours ago Up 3 hours 0.0.0.0:30002->30000/tcp, :::30002->30000/tcp SFCam2
7970ab7bece9 registry.gitlab.com/innovatrics/smartface/sf-access-controller:v5_1.9.1 "dotnet SmartFace.Ac…" 3 hours ago Up 3 hours 0.0.0.0:5050->80/tcp, :::5050->80/tcp SFAccessController
c812bd168f96 registry.gitlab.com/innovatrics/smartface/sf-station:v5_1.20.0 "docker-entrypoint.s…" 3 hours ago Up 3 hours 0.0.0.0:8000->8000/tcp, :::8000->8000/tcp SFStation
You now know the names of the services: SFApi, SFCam3, SFGraphQLApi, SFBase, SFCam2, SFAccessController, SFStation etc.
Once you have a container name you would like to know more about you can invoke the logs by command:
sudo docker logs <ContainerName>
To allow logs to be continuously fed to your screen, please use additional parameter -f, such as:
sudo docker logs <ContainerName> -f
To see a continuous logs of events as they happen across the whole setup at once (useful for real time debugging), you can run command below in the folder where the docker-compose.yml file is located:
sudo docker-compose logs --tail=0 -f
All the logs can be scraped and organized into a central log system such as Grafana Loki within a customized setup and deployment.
Logs Maintenance
In a system that runs for a while the amount of logs can actually take a significant amount of the server’s storage space. To list the existing docker logs and size they occupy on a hard drive, please run the command below:
sudo du -h $(docker inspect --format='{{.LogPath}}' $(docker ps -qa))
It is possible the amount of data kept in the logs might be substantial on your SmartFace installation it would be reasonable to limit the amount of logs to be stored. You can limit the maximum size of a log and the amount of logs to be stored by adjusting the docker-compose.yml file. Add and adjust the logging section for each container as per snippet below.
api:
image: ${REGISTRY}sf-api:${SF_VERSION}
logging:
driver: "json-file"
options:
max-file: 5
max-size: 10m