DEPLOYMENT_GUIDE.md

🚀 Hugging Face Spaces Deployment Guide (Docker + Streamlit)

This guide will walk you through deploying your RAG system to Hugging Face Spaces using Docker with Streamlit.

📋 Prerequisites

• Hugging Face account
• All files from the huggingface_deploy/ folder
• Basic understanding of Docker (optional)

🎯 Step-by-Step Deployment

Step 1: Create a New Space

1. Go to Hugging Face Spaces:

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

2. Configure your Space:

   • Owner: Choose your username or organization
   • Space name: Choose a unique name (e.g., my-rag-system)
   • License: Choose appropriate license (e.g., MIT)
   • SDK: Select Docker
   • Visibility: Choose Public or Private
   • Hardware: Select appropriate hardware (CPU is sufficient for basic usage)

3. Click "Create Space"

Step 2: Upload Files

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 files from the deployment folder:

cp -r ../huggingface_deploy/* .

3. Commit and push:

git add .
git commit -m "Initial RAG system deployment with Docker"
git push

Option B: Using Web Interface

1. Upload files manually:
   • Go to your Space's "Files" tab
   • Click "Add file" → "Upload files"
   • Upload all files from the huggingface_deploy/ folder:
     • app.py
     • rag_system.py
     • pdf_processor.py
     • requirements.txt
     • Dockerfile
     • .dockerignore
     • README.md

Step 3: Configure the Space

1. Set up environment variables (optional):

   • Go to your Space's "Settings" tab
   • Add environment variables if needed:

     EMBEDDING_MODEL=all-MiniLM-L6-v2
     GENERATIVE_MODEL=Qwen/Qwen2.5-1.5B-Instruct
     

2. Configure hardware (if needed):

   • Go to "Settings" → "Hardware"
   • Select appropriate hardware based on your needs

Step 4: Deploy and Test

1. Wait for deployment:

   • Hugging Face will automatically build and deploy your Docker container
   • This may take 10-15 minutes for the first deployment (model downloads)

2. Test your application:

   • Visit your Space URL: https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
   • Upload a PDF document
   • Ask questions to test the RAG system

🔧 Docker Configuration

Dockerfile Features

• Base Image: Python 3.10 slim
• System Dependencies: build-essential, curl
• Health Check: Monitors Streamlit health endpoint
• Environment Variables: Configured for Streamlit
• Port: Exposes port 8501

Local Docker Testing

You can test the Docker build locally:

# Build the Docker image
docker build -t rag-system .

# Run the container
docker run -p 8501:8501 rag-system

# Or use docker-compose
docker-compose up --build

🔧 Configuration Options

Environment Variables

You can customize your deployment by setting these environment variables in your Space settings:

# Model configuration
EMBEDDING_MODEL=all-MiniLM-L6-v2
GENERATIVE_MODEL=Qwen/Qwen2.5-1.5B-Instruct

# Chunk sizes
CHUNK_SIZES=100,400

# Vector store path
VECTOR_STORE_PATH=./vector_store

# Streamlit configuration
STREAMLIT_SERVER_PORT=8501
STREAMLIT_SERVER_ADDRESS=0.0.0.0
STREAMLIT_SERVER_HEADLESS=true

Hardware Options

• CPU: Sufficient for basic usage, slower inference
• T4: Good for faster inference, limited memory
• A10G: High performance, more memory
• A100: Maximum performance, highest cost

🐛 Troubleshooting

Common Issues

1. Build Fails

   • Check that all required files are uploaded
   • Verify requirements.txt and Dockerfile are correct
   • Check the build logs for specific errors

2. Model Loading Errors

   • Ensure internet connectivity for model downloads
   • Check model names are correct
   • Verify sufficient disk space

3. Memory Issues

   • Use smaller models
   • Reduce chunk sizes
   • Upgrade to higher-tier hardware

4. Slow Performance

   • Upgrade hardware tier
   • Use smaller embedding models
   • Optimize chunk sizes

5. Docker Build Issues

   • Check .dockerignore excludes unnecessary files
   • Verify Dockerfile syntax
   • Check for missing dependencies

Debug Mode

To enable debug logging, add this to your app.py:

import logging
logging.basicConfig(level=logging.DEBUG)

📊 Monitoring

Space Metrics

• Build Status: Check if Docker build was successful
• Runtime Logs: Monitor application logs
• Resource Usage: Track CPU and memory usage
• Error Logs: Identify and fix issues

Docker Logs

Check Docker logs in your Space:

• Go to "Settings" → "Logs"
• Monitor build and runtime logs
• Look for error messages

🔒 Security Considerations

1. File Upload:

   • Validate PDF files before processing
   • Implement file size limits
   • Check file types

2. Model Access:

   • Use appropriate model access tokens
   • Consider private models for sensitive data

3. Data Privacy:

   • Be aware that uploaded documents are processed
   • Consider data retention policies

4. Docker Security:

   • Use non-root user in Dockerfile
   • Minimize attack surface
   • Keep base images updated

📈 Scaling

For Production Use

1. Multiple Spaces:

   • Create separate Spaces for different use cases
   • Use different hardware tiers as needed

2. Custom Domains:

   • Set up custom domains for your Spaces
   • Use proper SSL certificates

3. Load Balancing:

   • Consider multiple Space instances
   • Implement proper caching strategies

🎉 Success Checklist

• Space created successfully with Docker SDK
• All files uploaded (including Dockerfile)
• Docker build completed without errors
• Application loads correctly
• PDF upload works
• Question answering works
• Search results display correctly
• Performance is acceptable

📞 Support

If you encounter issues:

1. Check the logs in your Space's "Logs" tab
2. Review this guide for common solutions
3. Search Hugging Face documentation
4. Create an issue in the project repository
5. Contact Hugging Face support for Space-specific issues

🚀 Next Steps

After successful deployment:

1. Test thoroughly with different document types
2. Optimize performance based on usage patterns
3. Add custom features as needed
4. Share your Space with others
5. Monitor usage and gather feedback

🔄 Updates and Maintenance

Updating Your Space

1. Make changes locally
2. Test with Docker locally
3. Push changes to your Space repository
4. Monitor the rebuild process

Version Management

• Use specific versions in requirements.txt
• Tag your Docker images
• Keep track of model versions

---

Happy deploying with Docker! 🐳🚀