Running DeepFace locally on Windows (NVIDIA GPU)

The DeepFace Docker image can run locally on a Windows machine with an NVIDIA GPU using Docker Desktop’s Linux container backend.

Requirements

• Windows with a supported NVIDIA GPU and up-to-date NVIDIA drivers.
• Docker Desktop configured to use the WSL 2 backend and Linux containers.
• WSL 2 installed and enabled.

The GPU must be available to containers through WSL 2. You can verify this from a WSL distribution using nvidia-smi.

Docker registry access

The image is hosted in the Docker registry at face2.tagroot.io.

To get access, open the Face2 neuron administration interface, create an administrator account with the Docker Registry role, then use the Docker Registry software module to create a registry user. A storage quota is not needed for a pull-only user.

Log in from PowerShell:

docker login face2.tagroot.io

Enter the registry username and password when prompted.

Get the Docker image

You can either pull the prebuilt image from the registry or build it from the neuron-deepface repository.

Option 1: Pull from the registry

From PowerShell:

docker pull face2.tagroot.io/deepface:1.0.0-gpu

Option 2: Build locally

Clone the repository and build using its GPU Dockerfile (DockerfileGpu):

git clone https://github.com/Trust-Anchor-Group/neuron-deepface.git
cd neuron-deepface
docker build -f DockerfileGpu -t deepface:local-gpu .

Start DeepFace

Start the prebuilt image with access to the NVIDIA GPU:

docker run -d --name deepface --restart unless-stopped --gpus all -p 127.0.0.1:5000:5000 face2.tagroot.io/deepface:1.0.0-gpu

If you built the image locally, replace face2.tagroot.io/deepface:1.0.0-gpu with deepface:local-gpu in the command above.

DeepFace is available at http://localhost:5000. The API’s /represent endpoint accepts POST requests. Model weights are downloaded by DeepFace when required, so the first request using a model may take longer.

GPU check

Check that Docker can access the NVIDIA GPU:

docker exec deepface nvidia-smi

If GPU access fails, check the NVIDIA Windows driver, WSL 2 configuration, and Docker Desktop’s Linux container backend.

Container logs

Follow the container logs to check that DeepFace starts correctly, initializes GPU support, and downloads the required model weights:

docker logs deepface -f

Model weights may be downloaded on the first request using a model. Check the logs for download errors or GPU initialization issues.

#docker, #deepface

DeepFace Setup

Architecture

Client Service → Gateway → Nginx → DeepFace Container

The client service uses a gateway to access the DeepFace worker. The gateway forwards DeepFace requests to the GPU server and can also be used for request queuing. Access to the DeepFace functionality on the gateway is IP-restricted to authorized services and development environments. Nginx on the GPU server only allows requests from the gateway and forwards them to the DeepFace container on port 5000.

Docker image

The DeepFace image can either be pulled from the Docker registry on the Face2 neuron at face2.tagroot.io or built locally from the neuron-deepface repository.

Option 1: Pull from the registry

To get access to the image:

1. Open the Face2 administration interface and create an administrator with the Docker Registry role.
2. Open the Docker Registry module at the bottom of the administration page.
3. Create a registry user. A storage limit is not needed for an account that only pulls images.
4. Log in to the registry and pull the image:

docker login face2.tagroot.io
docker pull face2.tagroot.io/deepface:1.0.0-gpu

Option 2: Build locally

Clone the repository and build using its GPU Dockerfile (DockerfileGpu):

git clone https://github.com/Trust-Anchor-Group/neuron-deepface.git
cd neuron-deepface
docker build -f DockerfileGpu -t deepface:local-gpu .

GPU worker

DeepFace runs in a Docker container on the GPU server, with access to the NVIDIA GPU through the NVIDIA container runtime. The container serves the DeepFace API on port 5000.

Start the container with GPU access and restart enabled:

docker run -d --name deepface --restart unless-stopped --gpus all -p 127.0.0.1:5000:5000 face2.tagroot.io/deepface:1.0.0-gpu

If the image was built locally, replace face2.tagroot.io/deepface:1.0.0-gpu with deepface:local-gpu.

The required recognition and anti-spoofing models are loaded by DeepFace at runtime. Missing model weights are downloaded automatically.

Nginx

Nginx exposes the worker at https://deepface.example.com/deepface/, forwarding requests to 127.0.0.1:5000. Only the gateway’s source IP is allowed to access this endpoint.

location /deepface/ {
    allow 192.0.2.10;
    deny all;

proxy_pass http://127.0.0.1:5000/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}

HTTPS certificates are managed with Certbot.

#deepface, #docker