Configuration

Configuration

Most things are adjustable in the UI. Environment variables cover the rest.

In the UI

Setting	Where	Default	What it does
Backend URL	Sidebar footer, or the first-launch dialog	http://localhost:8000	Which backend the frontend talks to
Face crop padding	Upload page, Processing Settings	45%	Extra space kept around a detected face when cropping its picture. Has a live preview.
Match tolerance	Upload page, Processing Settings	0.50	How close two faces must be to count as the same person. Lower is stricter.
Visual effects	Sidebar, Effects	all on	Edge animation, glow, node shadows, hover highlighting, transitions, minimap

Tolerance is worth understanding. At 0.50, people who look alike are occasionally merged. Lowering it to around 0.45 splits them apart, at the cost of sometimes recording one person twice. You can always fix the result by hand afterwards, and merging is reversible.

Both settings apply to the next run, not to results you already have.

Environment variables

Set these on the backend process.

FACE_GALLERY_ALLOWED_ORIGINS

Comma-separated list of frontend origins the backend accepts requests from.

Default: https://face-gallery.mrbean.dev, plus localhost and 127.0.0.1 on ports 5173 and 4173.

Needed when you serve the frontend from anywhere else. Browsers block cross-origin requests the backend has not opted into, so a frontend on an unlisted origin fails with a CORS error.

FACE_GALLERY_ALLOWED_ORIGINS="https://photos.example.com,http://localhost:4173"

A literal * is not accepted, because credentialed requests are enabled.

FACE_GALLERY_DATA_DIR

Where uploads, results, the thumbnail cache, and the SQLite database live.

Default: the current directory when run from source; the per-user application directory when run as the packaged executable (see Running Your Own Backend).

FACE_GALLERY_DATA_DIR=/mnt/photos/face-gallery

Useful for putting the data on a larger disk. The directory is created if it does not exist.

Upload limits

Requests exceeding a limit are rejected with HTTP 413, and any files already written for that request are cleaned up.

Variable	Default	Limits
FACE_GALLERY_MAX_FILE_BYTES	50 MB	A single uploaded file
FACE_GALLERY_MAX_REQUEST_BYTES	500 MB	One upload request in total
FACE_GALLERY_MAX_IMAGES_PER_JOB	10000	Images in one session
FACE_GALLERY_MAX_ZIP_DECOMPRESSED_BYTES	1 GB	Total decompressed size of a ZIP

The ZIP limit is a decompression-bomb guard: each member's declared size is checked before it is read, and a running total is kept.

Raise these if you process large batches. Every uploaded file is held in memory while it is validated, so raising them raises peak memory use — see Deployment for measured numbers.

Processing constants

These are module-level constants rather than environment variables. Change them in face-detection-webapp/backend/processing.py.

Constant	Default	Effect
TOLERANCE	0.5	Same as the tolerance setting above
FACE_CROP_PADDING	0.45	Same as the crop padding setting above
DETECTION_MAX_LONG_EDGE	1600	Photos are scaled to this on the long edge before detection

DETECTION_MAX_LONG_EDGE trades speed for bounding-box precision. Detection cost scales with pixel count, so on a 12 MP photo 1600 px is roughly twice as fast as full resolution. The recorded boxes are then within about 30 px of the full-resolution result, which is comfortably inside the crop padding but slightly visible if you look closely at drawn boxes. Raising it to 2400 tightens the boxes and gives back some of the speed.