Deploy InsightFace Server with Docker

Choose one block and run it from the repository root. It uses the supplied Compose file directly; that file selects the image to pull. If you already have the current checkout, skip git clone and enter its root.

After startup, open http://SERVER:18097/ for CPU or http://SERVER:18098/ for CUDA 12. The model installer accepts the model terms with --accept-license; review those terms before running it.

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, WebP, or BMP 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.

For a new deployment, append --enable-liveness to the model-install command above. Installation verifies the required models and saves the activation settings before the first startup.

For an existing deployment, use the matching command below, then restart the server. Plain model installation and models addons install liveness only install models; they do not enable liveness.

After installation succeeds, restart the running service. An existing container does not reload saved settings with up -d alone. Liveness remains off by default, and enrollment has its own liveness_on_registration switch.

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.

The installer supports buffalo_l, buffalo_m, buffalo_s, buffalo_sc, antelopev2, raccoon_s, and raccoon_l. Server uses only detection and recognition from Raccoon, without its PrivateFrame verifier. A model switch requires a compatible Collection and re-enrollment or a separate data migration.

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.

Persist /data, models, and server/config. Back up SQLite and configured face crops together while writes are stopped, or use a SQLite-safe snapshot. Protect these paths and backups as biometric data. Enable API-key authentication and HTTPS before network exposure.

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.

The supplied containers run as root (0:0), with one writable /models mount and a writable configuration directory. Compose creates the model root, and addon installation creates addons/ as needed. No host UID/GID or manual permission setup is required. The container root filesystem remains read-only.

Stop writes and back up the database and any crops first. Update the repository deployment files and merge your custom settings while preserving server/config/server.toml, models, the original project and data-volume names, ports, and API key. Use the matching Compose file below, including your existing overrides and project name if customized.

Pull both images and recreate the server. restart alone does not apply a new image or mount changes. Check health, the execution provider, existing Collections and People, and one known search. Keeping the same recognition model and embedding contract preserves existing samples; switching models is a separate migration. Update the Python SDK from the same current checkout.

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.

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.