Deploy InsightFace Server with Docker

Run commands from the root of a complete InsightFace checkout and choose one Compose stack. CPU is the simplest evaluation path and publishes port 18097. CUDA publishes port 18098 and requires a compatible NVIDIA Driver plus NVIDIA Container Toolkit; do not install host CUDA or cuDNN for this container.

The commands below deliberately use the non-interactive --accept-license option and immediately verify buffalo_l. Use it only after your organization has reviewed and accepted the displayed model terms. The same installer also supports buffalo_m, buffalo_sc, and antelopev2.

The Server source code and Python SDK are MIT-licensed, but model files and weights are not covered by that MIT license. Public InsightFace model packages, including buffalo_l, are generally limited to non-commercial academic research unless InsightFace has issued a separate commercial authorization; self-hosting the Server does not grant commercial model rights.

Installation writes manifest.json and a signed MODEL.LICENSE into server/.models. Verification checks package identity, the signed license, validity dates, and current authorization. The license identifies the model and permitted use; it is a compliance credential, not DRM and not a checksum of the model files.

Start only the stack you installed. Open http://SERVER:18097/ for CPU or http://SERVER:18098/ for CUDA. The health request confirms that the HTTP service is responding; before enrolling data, also inspect Dashboard or System and confirm that the service, database, model, and execution provider are ready.

A CUDA deployment must report CUDAExecutionProvider. Startup validates the GPU, Driver, CUDA/cuDNN/ONNX Runtime versions, real detector and recognizer sessions, provider placement, and warm-up inference. It terminates on failure instead of silently falling back to CPU.

In Collections, create a stable ID such as employees. Choose a search profile advertised by System, set capacity for your memory budget, and begin with the default raw-cosine threshold of 0.4. A Collection is pinned to its model identity, digest, embedding dimension, preprocessing version, and detection profile contract.

In People, select the Collection and register one Person with one or more clear JPEG, PNG, or WebP photos. Standard review is a useful starting point because it checks that exactly one usable face meets size, confidence, sharpness, brightness, and pose rules. Batch enrollment can partially succeed, so inspect each rejection reason rather than resubmitting the entire batch blindly.

In Search, select the same Collection and upload a different photo of that Person. Results are sorted by raw cosine similarity, and a Person's score is the best score among their FaceSamples. Similarity is not a probability. A successful no-match is an empty list, not a Server error.

The supplied Compose files default to authentication disabled for isolated evaluation. Before any other user or network can reach the service, enable authentication and set one long, random API key in the deployment secret environment. Restart the chosen stack with those values; the Web UI can keep the key in memory for the current browser tab.

Terminate HTTPS at a trusted reverse proxy, expose only required origins instead of broad CORS, add edge rate/body/time limits, and restrict access to Docker, /data, /models, and backups. Never log images, embeddings, RTSP credentials, or API keys. Treat every stored face artifact as biometric data.

SQLite in /data is the durable source of truth, while the exact-search indexes in memory are disposable. The Compose stack mounts the model directory read-only and keeps /data in a named volume. Back up the SQLite database and any configured crop storage together while writes are stopped, or use a SQLite-safe snapshot method.

Use the complete down command for the stack you started. Plain down removes containers and the network but preserves the named database volume. Never append -v: docker compose down -v permanently deletes that named data volume.

Start with the health endpoint, then inspect System and the selected Compose stack's container status and logs. On CUDA, a startup failure is intentional if the Driver, GPU, model sessions, CUDAExecutionProvider, provider audit, or warm-up check fails; there is no silent CPU fallback.

Every response carries x-request-id, and error bodies expose a request_id. Preserve that identifier with the relevant log window when reporting a problem. A 401 unauthorized usually means the current tab has no key or the key was rotated; 409 collection_model_mismatch means the Collection belongs to another model contract; 422 face_not_found means no usable face was selected.