README.md

metadata

title: MacHub
emoji: 🏢
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false

Machub Face Recognition Attendance Backend

A production-ready, ONNX-only face detection and recognition backend built with FastAPI, designed to be deployed on Hugging Face Spaces (free CPU tier).

---

Folder Structure

machub-hf-space/
├── app.py                  ← FastAPI main server
├── detector.py             ← YOLOv8 face detection using ONNX Runtime
├── recognizer.py           ← InsightFace ArcFace matching with CLAHE preprocessing
├── firebase_helper.py      ← Firestore read/write operations (IST & retry resilient)
├── keep_alive.py           ← Prevents Hugging Face Space from sleeping
├── requirements.txt        ← ONNX-only python dependencies
├── Dockerfile              ← Docker container configuration for HF Spaces
├── .env.example            ← Environment variables template
├── models/
│   └── README.md           ← Model download links and configuration details
└── README.md               ← Setup, test, and deployment guide (this file)

---

Setup & Deployment Guide

STEP 1: Create a Hugging Face Space

1. Go to huggingface.co/new-space.
2. Choose a name: machub-attendance.
3. Select Docker as the SDK.
4. Select Blank template.
5. Visibility: Private (recommended to keep endpoints hidden).
6. License: MIT or any.
7. Click Create Space.

STEP 2: Add Secrets in Hugging Face Space Settings

Go to your Space Settings page, scroll down to Variables and Secrets, and add the following Secret keys (not variables):

Secret Key	Description / Example Value
FIREBASE_PROJECT_ID	Your Firebase project ID (e.g., machub-6af39)
FIREBASE_PRIVATE_KEY_ID	Your Firebase credentials Private Key ID
FIREBASE_PRIVATE_KEY	Your Firebase Private Key (include the begin/end block headers and replace literal newlines if needed, e.g. -----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n)
FIREBASE_CLIENT_EMAIL	Firebase Client Email (e.g., firebase-adminsdk-...@...gserviceaccount.com)
FIREBASE_CLIENT_ID	Your Firebase Client ID
API_SECRET_KEY	Generate a random 32-character string. Save it here AND in machub-admin .env under VITE_HF_API_KEY.
SPACE_URL	Your Space direct URL (e.g., https://username-machub-attendance.hf.space)

Note: The FastAPI backend automatically initializes using these secrets.

STEP 3: Clone and Push Code

1. Clone your Hugging Face Space repository:

   git clone https://huggingface.co/spaces/YOUR_USERNAME/machub-attendance
   

2. Copy all files from C:/Projects/Machub/machub-hf-space/ (except the models/ ONNX files to comply with Git repository sizes) into the cloned directory.
3. Commit and push:

   git add .
   git commit -m "deploy: initial face recognition FastAPI server"
   git push
   

4. Hugging Face will automatically build and run the Docker image (takes 3-5 minutes). On first boot, the space will auto-download the YOLOv8 and ArcFace models from their releases.

STEP 4: Keep Space Awake 24/7 (UptimeRobot)

1. Go to uptimerobot.com and create a free account.
2. Click Add New Monitor.
3. Monitor Type: HTTPS.
4. Friendly Name: Machub KeepAlive.
5. URL: https://YOUR_USERNAME-machub-attendance.hf.space/health
6. Monitoring Interval: Every 5 minutes.
7. Create Monitor. This keeps your Space awake permanently for free!

---

Local Development & Testing

Before deploying, you can test the backend server locally on your machine.

Running Locally

1. Navigate to the folder:

   cd C:/Projects/Machub/machub-hf-space
   

2. Copy .env.example to .env and fill in your Firebase project credentials.
3. Install dependencies:

   pip install -r requirements.txt
   

4. Run the Uvicorn dev server:

   # If running on Windows, disable the OpenSSL AES-NI acceleration hardware bug:
   $env:OPENSSL_ia32cap="~0x200000200000000"
   python -m uvicorn app:app --reload --port 7860
   

---

API Testing with Curl Commands

Open a separate terminal window and run the following commands to test. Replace your-random-secret-key-here with the API_SECRET_KEY value configured in your .env.

1. Health Check (Public)

curl -X GET http://localhost:7860/health

Expected Response:

{
  "status": "online",
  "models": {
    "detector": true,
    "recognizer": true
  },
  "firebase": true,
  "version": "1.0.0"
}

2. Enroll a Student (Authenticated)

Uploads photos of a student to extract and save their face embedding to Firestore.

curl -X POST http://localhost:7860/enroll \
  -H "X-API-Key: your-random-secret-key-here" \
  -F "roll_no=BCA001" \
  -F "name=Test Student" \
  -F "division=BCA-A" \
  -F "photos=@/path/to/photo1.jpg" \
  -F "photos=@/path/to/photo2.jpg"

3. Scan a Classroom Frame (Authenticated)

Uploads a classroom frame to match faces and log attendance.

curl -X POST http://localhost:7860/scan \
  -H "X-API-Key: your-random-secret-key-here" \
  -F "frame=@/path/to/classroom_frame.jpg" \
  -F "period=1" \
  -F "division=BCA-A"