Running Your Own Backend

Running Your Own Backend

face-gallery.mrbean.dev is public and free to use — no sign-up, no account. But it deliberately has no server behind it. It is a static page, and it cannot do anything until you give it a backend.

That backend runs on your machine. Local backends are fully supported and are the normal way to use the app: your photos are uploaded to it, processed by it, and stored by it, and they never leave your computer. Nobody who runs the hosted site can see them, because there is nothing on that side that ever receives them.

There are two ways to get a backend running.

Option 1: the prebuilt executable

Download the file for your platform from the Releases page.

Platform	Asset
Linux (x86_64)	FaceGallery-linux-x86_64
macOS (Apple Silicon)	FaceGallery-macos-arm64
Windows (x64)	FaceGallery-windows-x86_64.exe

Run it. It starts the backend, waits for it to come up, and opens your browser at the hosted frontend already connected. Nothing to configure.

Leave the window open while you use the app. Closing it stops the backend.

Intel Macs have no prebuilt binary, because the prebuilt dlib wheel is Apple Silicon only. Use Option 2 or build it yourself.

The binaries are unsigned

Code signing needs a paid Apple Developer account and a Windows certificate, so the binaries are unsigned and your OS will complain the first time.

macOS — "cannot be opened because the developer cannot be verified": right-click the file and choose Open, or clear the quarantine flag:

xattr -d com.apple.quarantine ./FaceGallery-macos-arm64
chmod +x ./FaceGallery-macos-arm64

Windows — SmartScreen shows "Windows protected your PC": choose More info, then Run anyway.

Linux — make it executable first:

chmod +x ./FaceGallery-linux-x86_64
./FaceGallery-linux-x86_64

Where your data is stored

Platform	Location
Linux	${XDG_DATA_HOME:-~/.local/share}/face-gallery
macOS	~/Library/Application Support/FaceGallery
Windows	%LOCALAPPDATA%\FaceGallery

That directory holds your uploads, the cropped face images, the thumbnail cache, and the SQLite database. Set FACE_GALLERY_DATA_DIR to put it somewhere else. Deleting the directory resets the app.

Option 2: run from source

Follow Quick Start to set up the backend, then start it:

cd face-detection-webapp/backend
.venv/bin/python -m uvicorn main:app --port 8000

Open face-gallery.mrbean.dev and enter http://localhost:8000 in the Connect to Backend dialog.

The ?backend= shortcut

You can skip the dialog by putting the backend URL in the link:

https://face-gallery.mrbean.dev/?backend=http://localhost:8000

The app stores the value and removes the parameter from the address bar, so a URL you copy afterwards stays clean. This is what the executable does for you.

Browser support

Safari does not work. It blocks all mixed content, including requests to localhost, so an HTTPS page can never reach your local backend. There is no workaround short of putting the backend behind HTTPS with a real certificate.

Use localhost, not 127.0.0.1. Firefox exempts localhost by name from mixed-content blocking, but not the raw IP address. Chrome accepts both; localhost works everywhere.

Browser	Works
Chrome / Edge	Yes
Firefox 84+	Yes, with localhost rather than 127.0.0.1
Safari	No

Serving the frontend yourself

If you build the frontend and serve it from your own origin, the backend will reject it until you say that origin is allowed:

FACE_GALLERY_ALLOWED_ORIGINS="http://localhost:4173" \
  .venv/bin/python -m uvicorn main:app --port 8000

See Configuration for the full list of variables.