DEPLOYMENT.md

🚀 Deploying Devam Jersey Server to Hugging Face Spaces

This guide will help you deploy your jersey similarity detection server to Hugging Face Spaces.

📋 Prerequisites

1. Hugging Face Account: Sign up at huggingface.co
2. Git: Ensure git is installed and configured
3. Python Environment: Python 3.9+ with pip

🎯 Quick Start

Option 1: Web Interface (Recommended)

1. Go to Hugging Face Spaces

   • Visit https://huggingface.co/spaces
   • Click "Create new Space"

2. Configure Your Space

   • Owner: Your username
   • Space name: devam-jersey-server (or your preferred name)
   • SDK: Select Docker
   • License: Choose appropriate license
   • Visibility: Public or Private
   • Click "Create Space"

3. Upload Your Files

   • In your new space, click "Files and versions"
   • Upload all project files:
     • inference_server.py
     • requirements.txt
     • Dockerfile
     • README.md
     • models/deepfashion2_yolov8s-seg.pt
     • index/jersey_metadata.npy
     • Any other necessary files

4. Monitor Build

   • Go to "Settings" → "Build logs"
   • Wait for the Docker build to complete
   • Your API will be available at https://YOUR_USERNAME-devam-jersey-server.hf.space

Option 2: Git Clone Method

1. Clone the Created Space

   git clone https://huggingface.co/spaces/YOUR_USERNAME/devam-jersey-server
   cd devam-jersey-server
   

2. Copy Your Project Files

   # Copy all your project files to this directory
   cp -r /path/to/your/project/* .
   

3. Commit and Push

   git add .
   git commit -m "Initial upload of Devam Jersey Server"
   git push
   

Option 3: CLI Method

1. Install huggingface_hub

   pip install huggingface_hub
   

2. Create Space via CLI

   huggingface-cli repo create devam-jersey-server --type space --space-sdk docker
   

3. Clone and Upload

   git clone https://huggingface.co/spaces/YOUR_USERNAME/devam-jersey-server
   cd devam-jersey-server
   # Copy files and push as in Option 2
   

🔧 Configuration

Environment Variables (Optional)

In your Space settings, you can add environment variables:

• MODEL_PATH: Path to your YOLO model
• INDEX_PATH: Path to your FAISS index
• DEVICE: cuda or cpu

Hardware Requirements

• CPU: Basic CPU is sufficient for testing
• GPU: For production use, consider upgrading to GPU-enabled space
• Memory: At least 4GB RAM recommended

🧪 Testing Your Deployment

1. Check Space Status

• Visit your space URL
• Check the "Logs" tab for any errors
• Verify the API is responding

2. Test Endpoints

# Test root endpoint
curl https://YOUR_USERNAME-devam-jersey-server.hf.space/

# Test DINO endpoint (upload an image)
curl -X POST https://YOUR_USERNAME-devam-jersey-server.hf.space/dino \
  -F "file=@test_image.jpg"

# Test FAISS endpoint
curl -X POST https://YOUR_USERNAME-devam-jersey-server.hf.space/faiss \
  -H "Content-Type: application/json" \
  -d '{"features": [0.1, 0.2, ...]}'

3. Use the Test Script

# Update the base_url in test_server.py
python test_server.py

🚨 Troubleshooting

Common Issues

1. Build Fails

   • Check Dockerfile syntax
   • Verify all files are uploaded
   • Check build logs for specific errors

2. Model Loading Errors

   • Ensure model files are properly uploaded
   • Check file paths in code
   • Verify model file integrity

3. Memory Issues

   • Consider using smaller models
   • Optimize Docker image
   • Upgrade to GPU space if needed

4. API Not Responding

   • Check space status
   • Verify port configuration (should be 7860)
   • Check logs for runtime errors

🐳 Docker Build Issues

Package Installation Errors

If you encounter errors like:

Package 'libgl1-mesa-glx' is not available

Solution 1: Use the updated Dockerfile with minimal dependencies Solution 2: Try the alternative Dockerfile:

# Rename the alternative Dockerfile
mv Dockerfile Dockerfile.backup
mv Dockerfile.alternative Dockerfile
git add .
git commit -m "Use alternative Dockerfile for compatibility"
git push

Solution 3: Use a different base image in your Dockerfile:

FROM python:3.9-bullseye
# or
FROM python:3.9-buster

OpenCV Compatibility Issues

If OpenCV fails to install or work:

• The project now uses opencv-python-headless which is more Docker-friendly
• This version doesn't require GUI libraries

Debug Commands

# Check space logs
# Go to Settings → Logs in your HF Space

# Test locally first
python inference_server.py
python test_server.py

# Check Docker build locally
docker build -t devam-jersey .
docker run -p 7860:7860 devam-jersey

📊 Monitoring

• Build Logs: Check after each push
• Runtime Logs: Monitor for errors during operation
• Space Analytics: Track usage and performance
• API Status: Verify endpoints are responding

🔄 Updates

To update your deployed space:

1. Make Changes Locally
2. Push to Git

   git add .
   git commit -m "Update description"
   git push
   

3. Monitor Build: Check build logs for success
4. Test: Verify changes work as expected

📚 Additional Resources

• Hugging Face Spaces Documentation
• Docker on HF Spaces
• FastAPI Documentation

🎉 Success!

Once deployed, your jersey similarity server will be available at:

https://YOUR_USERNAME-devam-jersey-server.hf.space

Share this URL with others to use your API!

---

Need Help? Check the Hugging Face Community for support.