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](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:**
```bash
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME
```

2. **Copy files from the deployment folder:**
```bash
cp -r ../huggingface_deploy/* .
```

3. **Commit and push:**
```bash
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:

```bash
# 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:

```bash
# 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`:

```python
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! 🐳🚀**