CompreFace

Installation (Deployment) options

Exadel CompreFace consists of several services and a database. Full architecture description and scaling tips you can find here. Each service is put to docker image for simpler usage, and they can be run separately. However, for a better user experience, CompreFace provides three distribution options that help install CompreFace easier. By default, CompreFace is delivered as a docker-compose configuration. But there are more options to install and run CompreFace. Each of them has its benefits and disadvantages.

Distribution Advantages Disadvantages Best for
Docker Compose (Default) Simple configuration
Simple run
Passed QA regression		 Requires Docker Compose
Runs on single machine		 Local installation
Kubernetes Simple to scale Requires Kubernetes cluster Production installation
Single docker container Simple configuration
Simple run		 Least reliable option
Runs on single machine		 Local installation if Docker Compose is not supported

Docker Compose

Docker-compose configuration allows simply run, configure, stop and restart CompreFace. To install CompreFace using docker-compose just follow instructions in getting started

Maintaining tips

  1. After you run CompreFace, wait at least 30 seconds until it starts. Do not stop it during this time, as it may corrupt database data during data migration.
  2. You can run docker-compose ps to see all CompreFace services. There should be 5 CompreFace services: compreface-core, compreface-api, compreface-admin, compreface-ui, compreface-postgres-db. If at least one of the services is not in Up status - CompreFace failed to start.
  3. To see the logs of service, run docker-compose logs -f <service>, e.g. docker-compose logs -f compreface-api. You also can run docker-compose logs -f to see the logs of all CompreFace services.
  4. Docker-compose automatically restarts all services if they fail. It also automatically starts them after you restart your machine.
  5. If you want to stop CompreFace, run docker-compose stop. You can also stop each container one by one, e.g. docker-compose stop compreface-core.
  6. To start stopped Compreface, run docker-compose start. You can also start each container one by one, e.g. docker-compose start compreface-core.
  7. If you want to restart CompreFace, run docker-compose restart. You can also restart each container one by one, e.g. docker-compose restart compreface-core.
  8. All the data is stored locally on your machine. It is stored in a named docker volume. This guarantees that if you stop or delete CompreFace docker containers, you won’t lose the data. To find the volume name, run docker volume ls, the name should be <CompreFace folder>_postgres-data, e.g. compreface_061_postgres-data.
  9. If you want to clear CompreFace installation, first stop it with docker-compose stop. Then delete the volume, e.g. docker volume rm compreface_061_postgres-data. Then run CompreFace again docker-compose up -d.
  10. To update the CompreFace version or change custom build, download new docker-compose.yml and .env files. Stop CompreFace with docker-compose down. Copy new files into the old CompreFace folder. Then run CompreFace with docker-compose up -d.

Troubleshooting

  1. Problem: compreface-core doesn’t run.

    Probable solution: please check if you have supported CPU or GPU. The default version of CompreFace requires an x86 processor and AVX support.

  2. Problem: compreface-admin doesn’t start and there are logs like Waiting for changelog lock....

    Solution: clear CompreFace installation (see #Maintaining-tips)

Kubernetes

You can find all Kubernetes scripts in CompreFace Kubernetes repository.

Single docker container

Except for other distribution options, here all services and the database are placed in one docker image. The obvious advantage of this approach is that it is the simplest way to start CompreFace. However, it has some limitations in maintaining and troubleshooting. E.g. it’s very difficult to stop or restart services one by one. Supervisord was used to maintain several services in one Docker container.

Requirements:

  1. Docker Engine for Linux or Docker Desktop for Windows and macOS
  2. CompreFace could be run on most modern computers with x86 processor and AVX support. To check AVX support on Linux run lscpu | grep avx command

To install CompreFace single docker container run command (you don’t need anything to download manually):

docker run -d --name=CompreFace -v compreface-db:/var/lib/postgresql/data -p 8000:80 exadel/compreface

To use your own database for storing the data, specify these environment variables: POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_URL, EXTERNAL_DB, e.g.:

docker run -d --name=CompreFace -e "POSTGRES_URL=jdbc:postgresql://url:port/db_name" -e POSTGRES_USER=user -e POSTGRES_PASSWORD=pass -e EXTERNAL_DB=true -p 8000:80 exadel/compreface

To run the custom version of CompreFace, specify it in the end, e.g.:

docker run -d --name=CompreFace -v compreface-db:/var/lib/postgresql/data -p 8000:80 exadel/compreface:0.6.0

To run custom builds you can use corresponding tags, e.g.:

docker run -d --name=CompreFace -v compreface-db:/var/lib/postgresql/data -p 8000:80 exadel/compreface:1.0.0-mobilenet

To run version with GPU, you need to specify --runtime=nvidia and corresponding tag, e.g.:

docker run -d --name=CompreFace -v compreface-db:/var/lib/postgresql/data --runtime=nvidia -p 8000:80 exadel/compreface:1.0.0-arcface-r100-gpu

Maintaining tips

  1. Start CompreFace in a single docker container takes at least 45 seconds. So long start is because of manual timings that help to start services in the right order.
  2. There is a possibility that the database starts too slow, then service compreface-admin will fail. Supervisord will restart it automatically and CompreFace should start properly.
  3. To check if the run is finished, you can check the logs docker logs CompreFace -f. If you see exited: startup (exit status 0; expected) log, it is finished.
  4. To check if CompreFace is run, run docker ps. It should be a container with the name CompreFace. You set the name of the container in run command name=CompreFace
  5. compreface-db in the run command is the name of the volume, all your data is stored locally in this volume. This guarantees that if you stop or delete CompreFace docker containers, you won’t lose the data.
  6. You can use environment variables from docker-compose version, e.g. to set API server limit you can run: 
    docker run -d -e "API_JAVA_OPTS=-Xmx8g" --name=CompreFace -v compreface-db:/var/lib/postgresql/data -p 8000:80 exadel/compreface`
  7. By default, docker won’t restart CompreFace if it fails or after your restart your machine. You can add this by adding --restart=always in run command: 
    docker run -d --name=CompreFace -v compreface-db:/var/lib/postgresql/data -p 8000:80 --restart=always exadel/compreface
  8. If you want to stop CompreFace, run docker stop CompreFace.
  9. To start stopped Compreface, run docker start CompreFace.
  10. If you want to restart CompreFace, run docker restart CompreFace.
  11. If you want to clear CompreFace installation, first stop it with docker stop CompreFace. Remove container with docker rm CompreFace. Then delete the volume docker volume rm compreface-db. Then run CompreFace again.
  12. To update the CompreFace version or change custom build, stop CompreFace with docker stop CompreFace. Remove container with docker rm CompreFace. Then run the new CompreFace version.
This site is open source. Improve this page.