---
title: Face Recognition System
emoji: 🧠
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: "6.16.0"
python_version: "3.10"
app_file: app.py
pinned: false
---

# Face Recognition & Photo Capture Web App

This repository provides a face recognition backend (Flask) and a small Gradio UI to register users and run recognition from images.

This README focuses on deploying to Hugging Face Spaces (either using the Gradio SDK or the Docker option).

Quick notes
- Python 3.10 recommended (native deps installed via Conda in the Dockerfile).
- Heavy native deps: `dlib`, `face-recognition` — builds can be large and slow on Spaces.

Deploy options

- Gradio SDK (recommended for simple Spaces):
	- Use the Gradio SDK entrypoint. This repo includes `gradio_app.py` which launches the Gradio interface.
	- If you prefer the SDK frontmatter approach, set `app_file` to `gradio_app.py` in your Space settings or rename `gradio_app.py` to `app.py`.
	- In the Space settings select `SDK: Gradio`, Python `3.10`, and the appropriate `app_file`.

- Docker (recommended if you need full control over system dependencies):
	- This repo includes a `Dockerfile` that installs native deps via Conda and launches the Gradio app by default.
	- Choose Docker when creating a Space and push this repo; set Secrets before building.

Required Secrets (add these in your Space Settings → Secrets)

- `SUPABASE_URL` — your Supabase project URL
- `SUPABASE_SERVICE_ROLE_KEY` — Supabase service role key (server-side) for uploads/deletes
- `STORAGE` — set to `supabase` to store images in Supabase Storage
- `ADMIN_USERNAME` — admin username (optional; default `admin`)
- `ADMIN_PASSWORD` — admin password (required to access admin endpoints)
- `APP_SECRET` — secret used for JWT signing
- Optional: `DATABASE_URL` (external Postgres), `AWS_S3_BUCKET`, `AWS_REGION`, `CLOUDINARY_*`

Supabase setup

- Create a Storage bucket named `captures` (the app uses `supabase.storage.from_('captures')`).
- Decide whether objects should be public. The code uses `get_public_url()`; if you prefer private objects, update the app to use signed URLs.

Local testing (recommended before pushing to Spaces)

```bash
# build locally (requires Docker)
docker build -t face-recog-app .

# run using local filesystem storage to avoid external services
docker run --rm -e STORAGE=local -e ADMIN_PASSWORD=adminpass -p 7860:7860 face-recog-app

# open http://localhost:7860
```

Deploying to Hugging Face Spaces (high level)

1. Create a new Space and choose `Gradio` SDK (or `Docker` if you prefer). If using Gradio SDK, set `app_file` to `gradio_app.py`.
2. Push this repository to the Space (add remote and git push).
3. In the Space Settings → Secrets, add the required `SUPABASE_*` keys, `ADMIN_PASSWORD`, and `APP_SECRET`.
4. Trigger a build and monitor logs for native dependency installation (may take several minutes).

Persistence and storage notes

- The container filesystem and local SQLite (`app.db`) are ephemeral on Spaces. To persist images and DB across rebuilds use Supabase Storage and an external Postgres (`DATABASE_URL`).
- The app's `STORAGE` setting controls where images are saved. Use `STORAGE=supabase` in Space Secrets to send images to Supabase Storage.

Security

- Keep `SUPABASE_SERVICE_ROLE_KEY` only in Secrets — never expose it to the client/browser.
- Use strong `APP_SECRET` and secure `ADMIN_PASSWORD` in production.

Troubleshooting

- Build fails or times out: heavy native deps (`dlib`) are the likely cause. Consider pre-building an image elsewhere and using Docker, or replacing `face-recognition` with a lighter alternative for initial testing.
- Supabase upload errors: verify the `captures` bucket exists and the service role key has storage permissions.

Files of interest

- `app.py` — Flask backend and REST API
- `gradio_app.py` — Gradio UI that integrates with the backend (used by Spaces Gradio SDK or Docker)
- `Dockerfile` — Docker image that installs native deps via Conda and runs `gradio_app.py`
- `.env.example` — example environment variables to copy into `.env` for local testing

If you want, I can:
- Update the Space frontmatter to set `app_file: gradio_app.py` for a Gradio SDK deployment.
- Help push this repo to a new Hugging Face Space and add the exact Secrets via the UI.