README.md

metadata

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)

# 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.