Quick Start

Quick Start

Running both halves locally from source.

You probably do not need to. The frontend is already hosted for free at face-gallery.mrbean.dev and works with a backend on your own machine, so the prebuilt executable is far less work and keeps your photos just as local. Build from source if you want to modify the app, or if you would rather not depend on a site you do not control.

Prerequisites

• Python 3.10 or newer (3.12 is what the project is developed against)
• Node.js 18 or newer, and npm
• A C++ toolchain, only if you install dlib from source — see Installing dlib below

1. Clone

git clone https://github.com/mrbeandev/Face-Gallery.git
cd Face-Gallery

2. Backend

cd face-detection-webapp/backend

python3 -m venv .venv
source .venv/bin/activate        # macOS / Linux
# .venv\Scripts\activate         # Windows

pip install -r requirements.txt
python -m uvicorn main:app --port 8000

The API is now on http://localhost:8000. Check it with:

curl http://localhost:8000/health

In development the backend stores uploads, results, thumbnails, and the SQLite database in the directory you ran it from.

The default --host is loopback, which is what you want. Do not bind 0.0.0.0 unless you intend to publish an unauthenticated photo backend to your whole network.

3. Frontend

In a second terminal:

cd face-detection-webapp/frontend
npm install
npm run dev

The app is now on http://localhost:5173. The Vite dev server proxies /api, /ws, /thumb, and /static to the backend, so no CORS setup is needed for local development.

4. Connect

Open http://localhost:5173. On first launch you are asked for the backend URL, prefilled with http://localhost:8000. Click Test & Connect.

You can skip the dialog entirely with http://localhost:5173/?backend=http://localhost:8000.

Installing dlib

face_recognition depends on dlib, which is compiled C++. Installing it from source needs CMake and a compiler:

Ubuntu / Debian

sudo apt update
sudo apt install -y cmake build-essential libopenblas-dev liblapack-dev libx11-dev

macOS

brew install cmake

Windows

Install CMake and the Visual Studio Build Tools with the "Desktop development with C++" workload.

Skipping the compile

A source build takes a long time and needs a fair amount of memory. The dlib-bin package ships prebuilt wheels for Linux x86_64 and aarch64, Windows x64, and Apple Silicon, and provides the same dlib module:

pip install dlib-bin
pip install --no-deps face_recognition face_recognition_models
pip install -r requirements.txt

This is what the release workflow does. See Building the Executable.

If the import fails

ModuleNotFoundError: No module named 'pkg_resources' means setuptools is missing. Python 3.12 virtual environments no longer include it, and setuptools 81 removed pkg_resources, which face_recognition_models needs:

pip install "setuptools<81"

requirements.txt already pins this. More in Troubleshooting.