DEPLOYMENT.md

🚀 Hugging Face Spaces Deployment Checklist

✅ Pre-Deployment Checklist

1. File Structure

• app.py - Main Streamlit application (entry point)
• download_images.py - Image downloading utilities
• photos_url.csv - Image dataset (25,000+ URLs)
• requirements.txt - Python dependencies
• README.md - Project documentation
• .gitignore - Clean repository

2. File Names (Critical for Hugging Face)

• Main app file: app.py (entry point at repo root)
• Dependencies: requirements.txt
• Documentation: README.md (contains HF Spaces metadata header)

3. Code Verification

• App imports successfully
• Dependencies are correctly specified
• No syntax errors
• Proper error handling

🎯 Hugging Face Spaces Setup

Step 1: Create New Space

1. Go to Hugging Face Spaces
2. Click "Create new Space"
3. Choose your repository
4. Select SDK: Streamlit ⭐ (CRITICAL)
5. Select License: Choose appropriate license
6. Click "Create Space"

Step 2: Upload Files

Include at minimum:

1. app.py (main application)
2. photos_url.csv (dataset of image URLs)
3. requirements.txt (dependencies)
4. README.md (metadata + documentation)
5. Optional: download_images.py (standalone utility)

Note: For Streamlit Spaces you do not need a custom Dockerfile; the platform runs app.py based on the README metadata.

Step 3: Configure Secrets (Optional for Text Search)

If you want text search powered by openai/clip-vit-base-patch32 via the Inference API:

1. Go to Space → Settings → Secrets
2. Add secret key: HF_TOKEN with your Hugging Face token value
3. Save

Step 4: Verify Deployment

1. Check that the Space shows "Building" status
2. Wait for build to complete (usually 2-5 minutes)
3. Verify the app loads without "No application file found" error
4. Test the interface functionality

🔧 Troubleshooting Common Issues

Issue: "No application file found"

Solution: Ensure app.py is the main file (not start_app.py)

Issue: Build fails

Solution: Ensure app.py and requirements.txt exist at repo root and the README has the metadata header

Issue: App loads but text search is disabled

Solution: Add HF_TOKEN secret to the Space. Image upload search works without it.

Issue: Images not downloading

Solution: Verify photos_url.csv is present and accessible

📋 Post-Deployment Verification

1. App Loading

• App loads without errors
• No "No application file found" message
• Streamlit interface appears

2. Functionality

• Search by ID works
• Range by Block works
• Images display correctly
• No Python errors in console

3. Performance

• App responds within reasonable time
• Image downloads work (if needed)
• No memory issues

🎉 Success Indicators

✅ App loads successfully
✅ No "No application file found" error
✅ Streamlit interface appears
✅ Search functionality works
✅ Images display correctly
✅ No Python errors in logs

📞 If Issues Persist

1. Check Space logs in Hugging Face interface
2. Verify file names match exactly
3. Ensure Streamlit SDK is selected
4. Check requirements.txt format
5. Verify app.py is the main entry point

---

Your app should now deploy successfully on Hugging Face Spaces! 🚀