DEPLOYMENT_CHECKLIST.md

HuggingFace Deployment Checklist

Use this checklist to ensure your project is fully prepared for deployment to HuggingFace Spaces.

Pre-Deployment Checks

✅ Code & Configuration

• app.py exists and has correct entry point
• requirements.txt is updated with all dependencies
• src/main.py has proper type annotations for Gradio compatibility
• spaces.yaml is configured for your resource needs
• .gitignore includes common Python ignore patterns
• .gitattributes has LFS configuration for .pth files

✅ Documentation

• README.md has HuggingFace Space headers (title, emoji, sdk, python_version, app_file)
• README.md includes usage instructions and feature descriptions
• DEPLOYMENT.md provides comprehensive deployment guide
• .env.example shows available environment variables
• LICENSE file is present (MIT recommended for open-source)

✅ Model & Data Files

• Model weights directory: data/weights/TO_BE_USED/ exists
• At least one model file found and accessible (*.pth files)
• Preprocessing data files exist: data/preprocess_data/ with:
  • label_encoder_pad_20.pickle
  • ohe_pad_20.pickle
  • scaler_pad_20.pickle
• Total project size < 25 GB (HF Spaces limit)
• .pth files tracked with Git LFS in .gitattributes

✅ Dependencies

• PyTorch version is specified (torch==2.4.1)
• Gradio version is compatible (gradio==4.44.1)
• All imports in code are in requirements.txt
• No local-only dependencies or custom packages
• opencv-python-headless used instead of opencv-python (for headless servers)

✅ Code Quality

• No hardcoded local paths (use os.path relative paths)
• No local file system access outside of project directory
• No network calls to external APIs that require authentication
• Proper error handling for missing model files
• App handles gracefully when run on CPU-only systems

✅ Performance

• Model loading is lazy (not at import/startup time)
• Model caching implemented to avoid reloading
• Queue enabled in Gradio for concurrent request handling
• Gradio version supports queue() method

✅ Git & Version Control

• Project is a Git repository (git init if needed)
• Remote added for HuggingFace: git remote add origin https://huggingface.co/spaces/<user>/<space>
• All source files are tracked: git add .
• Initial commit created: git commit -m "Initial commit"
• No .git/config with wrong remote URL

✅ HuggingFace Account Setup

• HuggingFace account created and verified
• Git credentials configured: huggingface-cli login
• SSH keys set up (if using SSH) or token saved
• Write access to target Space confirmed

Deployment Steps

1. Create Space on HuggingFace

   • Go to https://huggingface.co/new
   • Name: skin-lesion-explainability (or preferred name)
   • Type: Space (not Model or Dataset)
   • SDK: Gradio
   • Python Version: 3.10
   • Visibility: Public (or Private)

2. Clone & Configure

   [ ] git clone https://huggingface.co/spaces/<username>/<space-name>
   [ ] cp -r /path/to/project/* .
   [ ] cd <space-name>
   

3. Verify Files

   [ ] ls -la app.py
   [ ] ls -la requirements.txt
   [ ] ls -la README.md
   [ ] ls -la spaces.yaml
   [ ] ls -la src/
   [ ] ls -la data/
   

4. Push to HuggingFace

   [ ] git add .
   [ ] git commit -m "Initial deployment"
   [ ] git push origin main
   

5. Monitor Build

   • Go to https://huggingface.co/spaces//
   • Check "Runtime" tab for build status
   • Watch logs for errors
   • Wait for "Running" status

Post-Deployment Verification

✅ Functional Testing

• App loads without errors (check Logs tab)
• Gradio interface appears in browser
• All input fields render correctly
• Model dropdown populated with choices
• Can select metadata groups
• Image upload works

✅ Feature Testing

• Upload test image succeeds
• Model inference completes (~30 sec first run, 5-15 sec cached)
• Attention heatmap generates correctly
• Metadata CSV preview displays
• Clear button resets all fields
• No errors in browser console (F12 to check)

✅ Performance Monitoring

• First inference: 30-60 seconds (acceptable with model loading)
• Subsequent inferences: 5-15 seconds
• Queue works with concurrent requests (if multiple users)
• Memory usage stable (check Runtime/Logs)

Troubleshooting Guide

Build Fails with ImportError

Solution:

1. Check requirements.txt - ensure all imports are listed
2. Read full error in Logs tab
3. Verify Python 3.10 is specified in spaces.yaml

Models Not Found at Runtime

Solution:

1. Verify data/weights/TO_BE_USED/ directory in repository
2. Check file sizes in Logs during startup
3. Ensure .pth files are fetched (Git LFS resolution)

CUDA Out of Memory

Solution:

1. Add to spaces.yaml: gpu: "A10G"
2. Or remove GPU line for CPU-only
3. Set env var: PYTORCH_CUDA_PER_PROCESS_MEMORY_FRACTION=0.5

App Loads but Inference Fails

Solution:

1. Check browser console for errors (F12)
2. Check Logs tab for Python errors
3. Verify all preprocessing files exist in data/preprocess_data/

Optimization Tips

Speed Up First Inference

• Pin GPU instance in spaces.yaml (if budget allows)
• Pre-load one model at startup (modify inference.py)

Reduce Memory Usage

• Use CPU-only mode (remove gpu line in spaces.yaml)
• Quantize models (advanced)

Handle More Concurrent Users

• Increase GRADIO_QUEUE_SIZE in environment
• Add GPU for faster inference
• Implement request timeout

Security Considerations

• No API keys/secrets in code
• Use .env.example for configuration templates
• Avoid downloading from untrusted sources
• Review third-party packages for vulnerabilities
• Model predictions should not persist user data

Documentation

• README.md has clear feature description
• DEPLOYMENT.md has step-by-step guide
• Code includes docstrings (especially inference.py)
• Comments explain non-obvious logic
• Example outputs shown in README

Final Checklist

• All items above are checked
• Tested locally: python app.py works
• Committed to git: git status shows clean
• Pushed to HuggingFace: git push origin main
• Build completed: Space shows "Running" status
• App functional: Can upload, select options, generate predictions
• Performance adequate: Inference completes in reasonable time
• Logs clean: No errors in Logs tab

Support Resources

• HuggingFace Spaces Docs: https://huggingface.co/docs/hub/spaces
• Gradio Documentation: https://gradio.app/docs
• PyTorch Hub: https://pytorch.org/hub/
• Community Forum: https://discuss.huggingface.co/

---

Status: ⏳ Ready to Deploy (after checking all boxes)

Last Verified: March 2026