DOCKER_SDK_SETUP.md

Docker SDK Setup Guide

Overview

The Research AI Assistant now uses Docker SDK instead of Gradio SDK for Hugging Face Spaces deployment. This provides more control and flexibility.

Changes Made

1. README.md Configuration

Changed from:

sdk: gradio
app_file: app.py

To:

sdk: docker
app_port: 7860

2. Dockerfile Configuration

Key Features:

• Base Image: Python 3.10-slim
• Entry Point: main.py (starts both Gradio and Flask API)
• Ports:
  • 7860: Gradio UI (primary, exposed by HF Spaces)
  • 5001: Flask API (background thread)
• Health Check: Monitors Gradio endpoint

How It Works

Startup Sequence

1. Docker Container Starts

   • Runs python main.py

2. main.py Initializes

   • Starts Flask API in background thread (port 5001)
   • Creates Gradio interface from app.py
   • Launches Gradio on port 7860

3. Both Services Available

   • Gradio UI: https://your-space.hf.space (port 7860)
   • Flask API: Available internally (port 5001)

File Structure

Research_AI_Assistant/
├── Dockerfile              # Main Dockerfile (used by HF Spaces)
├── Dockerfile.hf           # Alternative/backup Dockerfile
├── README.md               # HF Spaces config (sdk: docker)
├── main.py                 # Entry point (starts Flask + Gradio)
├── app.py                  # Gradio interface definition
└── flask_api.py            # Flask API (started by main.py)

Benefits of Docker SDK

1. More Control

• Full control over container environment
• Can install system dependencies
• Custom startup scripts

2. Multiple Services

• Can run multiple processes (Gradio + Flask)
• Better resource management
• Health checks

3. Flexibility

• Not limited to Gradio's constraints
• Can add additional services
• Better debugging

4. Production Ready

• Standard Docker patterns
• Easier to migrate to other platforms
• Better for CI/CD

Deployment

On Hugging Face Spaces

1. Push to Repository

   git push origin main
   

2. HF Spaces Auto-Builds

   • Detects sdk: docker in README.md
   • Builds Docker image from Dockerfile
   • Exposes port 7860

3. Services Start

   • Flask API starts in background
   • Gradio UI launches on port 7860
   • Both share orchestrator instance

Local Testing

Test the Docker build locally:

# Build image
docker build -t research-assistant .

# Run container
docker run -p 7860:7860 -p 5001:5001 \
  -e HF_TOKEN=your_token \
  research-assistant

Port Configuration

Exposed Ports

• 7860: Gradio UI (primary, exposed by HF Spaces)

  • Accessible at: https://your-space.hf.space

• 5001: Flask API (internal, background thread)

  • Not directly exposed by HF Spaces
  • Can be accessed via port forwarding if needed

Internal Communication

• Flask API runs in same container
• Both services share Python process
• Shared orchestrator instance
• No network overhead

Environment Variables

Set in HF Spaces Secrets:

HF_TOKEN=your_huggingface_token
ENABLE_FLASK_API=true      # Default: true
FLASK_PORT=5001            # Default: 5001
FLASK_HOST=0.0.0.0        # Default: 0.0.0.0

Health Checks

The Dockerfile includes a health check:

HEALTHCHECK --interval=30s --timeout=30s --start-period=60s --retries=3 \
    CMD curl -f http://localhost:7860/ || exit 1

• Checks Gradio endpoint every 30 seconds
• 60-second startup period (allows initialization)
• 3 retries before marking unhealthy

Troubleshooting

Issue: Build Fails

Check:

1. Dockerfile syntax is correct
2. Requirements.txt has all dependencies
3. Python 3.10 is available

Solution:

# Test build locally
docker build -t test-build .

Issue: Port Not Accessible

Check:

1. app_port: 7860 in README.md
2. Gradio is listening on 0.0.0.0:7860
3. No firewall blocking

Solution:

• Verify in logs: "Running on local URL: http://0.0.0.0:7860"

Issue: Flask API Not Starting

Check:

1. Logs show Flask initialization
2. ENABLE_FLASK_API=true (default)
3. Port 5001 not conflicting

Solution:

• Check logs for "Starting Flask API in background thread..."
• Verify Flask thread starts successfully

Comparison: Gradio SDK vs Docker SDK

Feature	Gradio SDK	Docker SDK
Setup	Simple	More control
Multiple Services	❌ Limited	✅ Full control
System Dependencies	⚠️ Limited	✅ Full access
Customization	⚠️ Limited	✅ Complete
Debugging	⚠️ Harder	✅ Easier
Port Configuration	⚠️ Fixed	✅ Flexible
Health Checks	❌ No	✅ Yes

Migration Notes

From Gradio SDK

If migrating from Gradio SDK:

1. ✅ README.md: Changed sdk: gradio → sdk: docker
2. ✅ Dockerfile: Created/updated to use main.py
3. ✅ Entry Point: Changed from app.py → main.py
4. ✅ Ports: Explicitly configured (7860, 5001)

What Still Works

• ✅ All Gradio functionality preserved
• ✅ All API endpoints work
• ✅ Flask API integration works
• ✅ Orchestrator initialization unchanged

Summary

✅ Docker SDK: More control and flexibility
✅ Dual Services: Gradio + Flask API
✅ Production Ready: Standard Docker patterns
✅ Health Checks: Built-in monitoring
✅ Flexible: Easy to extend and customize

The application now uses Docker SDK for better control and flexibility while maintaining all existing functionality.