DEPLOYMENT.md

Hugging Face Spaces Deployment Guide

Quick Deployment Steps

1. Create a new Space on Hugging Face

   • Go to https://huggingface.co/new-space
   • Choose "Docker" as the SDK
   • Set visibility (public/private)

2. Upload your files

   • Upload all files from this directory to your Space
   • Make sure these files are included:
     • app.py (main Flask application)
     • database.py (database functions)
     • requirements.txt (Python dependencies)
     • Dockerfile (container configuration)
     • README.md (Space configuration)
     • Ultra_Optimized_RandomForest.joblib (ML model)
     • ultra_optimized_scaler.joblib (scaler)
     • face_landmarker_v2_with_blendshapes.task (MediaPipe model)
     • templates/ folder with HTML files

3. Configure Environment Variables (Optional)

   • Go to Settings → Repository secrets
   • Add these if you want full functionality:
     • CLOUDINARY_CLOUD_NAME
     • CLOUDINARY_API_KEY
     • CLOUDINARY_API_SECRET
     • MONGO_URI

4. Deploy

   • The Space will automatically build and deploy
   • Check the logs for any errors

Key Changes Made for HF Spaces

1. README.md Configuration

• Added proper HF Spaces metadata
• Set sdk: docker
• Set app_port: 7860

2. Flask App Configuration

• Changed port from 5000 to 7860 (HF Spaces default)
• Set host to 0.0.0.0 for external access
• Disabled debug mode for production

3. Dockerfile Optimization

• Simplified for HF Spaces deployment
• Uses gunicorn for production serving
• Proper port configuration (7860)

4. Error Handling

• Added graceful handling for missing environment variables
• Models can run without Cloudinary/MongoDB
• Health check endpoint for monitoring

5. Requirements

• Added protobuf version for compatibility
• All dependencies pinned to stable versions

Troubleshooting

Common Issues:

1. "This Space has encountered a config error"

   • Check README.md has proper metadata
   • Ensure Dockerfile exists and is correct
   • Verify all required files are uploaded

2. Model loading errors

   • Ensure model files are in the root directory
   • Check file permissions
   • Verify file sizes are under HF Spaces limits

3. Port binding errors

   • Make sure app runs on port 7860
   • Check Dockerfile exposes correct port

4. Memory issues

   • HF Spaces has memory limits
   • Consider model optimization if needed

Health Check

Visit /health endpoint to check:

• Model loading status
• Environment variable availability
• Overall system health

Features Available Without Environment Variables

• Face shape detection
• Image analysis
• Confidence scores
• Facial measurements
• Web interface

Features Requiring Environment Variables

• Image storage (Cloudinary)
• Data persistence (MongoDB)
• Analysis history

The app will work fully without these services, just with limited storage capabilities.