HUGGINGFACE_DEPLOYMENT.md

Hugging Face Deployment Guide

This guide will help you deploy the Smart Budget Recommendation API to Hugging Face Spaces.

Prerequisites

1. A Hugging Face account (sign up at https://huggingface.co)
2. MongoDB connection string ready
3. Git installed (optional, you can also use the web interface)

Step-by-Step Deployment

Step 1: Create a New Space

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Fill in the details:
   • Space name: smart-budget-recommendation (or your preferred name)
   • SDK: Select Docker
   • Visibility: Choose Public or Private
4. Click "Create Space"

Step 2: Add secrets (MongoDB and optional OpenAI)

1. In your Space, go to Settings (gear icon)
2. Navigate to Variables and secrets section
3. Click New secret
4. Add the following secrets:
   • Name: MONGODB_URI
     • Value: mongodb://expenseuser:Kem_6o%3F%[email protected]:27017/expense?authSource=admin
   • Name: OPENAI_API_KEY (optional, enables GPT-based recommendations)
     • Value: sk-...
5. Click Add secret after each entry

Step 3: Upload Files

You can upload files in two ways:

Option A: Using Git (Recommended)

1. Clone your Space repository:

git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

2. Copy all files from this project:

   • app/ directory (all Python files)
   • Dockerfile
   • requirements.txt
   • .dockerignore
   • README.md (optional)

3. Commit and push:

git add .
git commit -m "Initial deployment"
git push

Option B: Using Web Interface

1. In your Space, click Files and versions tab
2. Click Add file → Upload files
3. Upload all files:
   • All files from app/ directory
   • Dockerfile
   • requirements.txt
   • .dockerignore

Step 4: Wait for Build

1. Hugging Face will automatically detect the Dockerfile and start building
2. You can monitor the build progress in the Logs tab
3. The build typically takes 2-5 minutes

Step 5: Verify Deployment

Once the build completes:

1. Your API will be available at: https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space
2. Test the health endpoint: https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/health
3. View API documentation: https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/docs

Testing Your Deployment

Using cURL

# Health check
curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/health

# Get recommendations (replace user123 with actual user_id)
curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/recommendations/user123

Using Python

import requests

BASE_URL = "https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space"

# Health check
response = requests.get(f"{BASE_URL}/health")
print(response.json())

# Get recommendations
response = requests.get(f"{BASE_URL}/recommendations/user123")
print(response.json())

Important Notes

1. Port Configuration: Hugging Face Spaces expect apps to serve on port 7860, so the Dockerfile exposes and binds to that port.

2. Environment Variables: Secrets such as MONGODB_URI (and optional OPENAI_API_KEY) are injected automatically into the container environment.

3. Cold Starts: The first request after inactivity may take longer (cold start). Subsequent requests will be faster

4. Resource Limits: Free Hugging Face Spaces have resource limits. For production use, consider upgrading

5. Custom Domain: You can add a custom domain in Space settings if needed

Troubleshooting

Build Fails

• Check the Logs tab for error messages
• Ensure Dockerfile is in the root directory
• Verify all required files are uploaded

Connection Errors

• Verify MONGODB_URI secret is set correctly
• Check MongoDB server is accessible from Hugging Face's servers
• Review connection string encoding (special characters should be URL-encoded)

API Not Responding

• Check the Logs tab for runtime errors
• Verify the application starts successfully
• Test the /health endpoint first

Updating Your Deployment

1. Make changes to your code locally
2. Commit and push to your Space repository
3. Hugging Face will automatically rebuild and redeploy

Support

For issues specific to:

• Hugging Face Spaces: Check Hugging Face Documentation
• This Application: Check the main README.md file