Hugging Face's logo

Spaces:
Abeshith
/
rag-chatbot
Sleeping

App Files Community
rag-chatbot / DEPLOYMENT.md
Abeshith's picture
Abeshith
Improved CI/CD pipeline with 3-stage
73d4d7e
preview code
|
raw
history blame contribute delete
6.99 kB

Hugging Face Deployment Guide

Complete step-by-step guide to deploy your RAG chatbot to Hugging Face Spaces via GitHub Actions CI/CD.

📋 Prerequisites

🚀 Deployment Steps

Step 1: Create Hugging Face Space

  1. Go to: https://huggingface.co/new-space

  2. Fill in details:

    Owner: [Your HF username]
Space name: rag-chatbot (or your choice)
License: MIT
Select SDK: Docker
Hardware: CPU basic (free) or upgrade to GPU

  3. Click "Create Space"

  4. Important: Copy your Space URL

    Example: https://huggingface.co/spaces/YourUsername/rag-chatbot

  5. Note down:

    • HF_USERNAME: Your Hugging Face username
    • HF_SPACE_NAME: The space name (e.g., rag-chatbot)

Step 2: Get Hugging Face Access Token

  1. Go to: https://huggingface.co/settings/tokens

  2. Click "New token"

  3. Fill in:

    Name: github-actions-deploy
Role: Write

  4. Click "Generate token"

  5. Copy the token (starts with hf_...) ⚠️ Save it immediately - you won't see it again!

Step 3: Add GitHub Secrets

  1. Go to: https://github.com/Abeshith/RAG/settings/secrets/actions

  2. Click "New repository secret" and add these 3 secrets:

    Secret 1:

    Name: HF_TOKEN
Value: [Paste your HF token from Step 2]

    Secret 2:

    Name: HF_USERNAME
Value: [Your Hugging Face username]

    Secret 3:

    Name: HF_SPACE_NAME
Value: rag-chatbot (or whatever you named it)

  3. Verify all 3 secrets are added

Step 4: Add Hugging Face Space Secrets

Your app needs API keys to run. Add them to HF Space:

  1. Go to your Space: https://huggingface.co/spaces/[username]/[space-name]

  2. Click "Settings" tab

  3. Scroll to "Repository secrets"

  4. Add these 5 secrets:

    Secret 1:
Name: GROQ_API_KEY
Value: [Your Groq API key]

Secret 2:
Name: MONGODB_URI
Value: [Your MongoDB connection string]

Secret 3:
Name: REDIS_URL
Value: [Your Redis connection URL]

Secret 4:
Name: QDRANT_URL
Value: [Your Qdrant cluster URL]

Secret 5:
Name: QDRANT_API_KEY
Value: [Your Qdrant API key]

  5. Click "Save" for each secret

Step 5: Trigger Deployment

Now everything is configured! Deploy your app:

Option A: Automatic (Push to GitHub)

# Make any small change (or just trigger workflow)
git commit --allow-empty -m "Trigger HF deployment"
git push origin main

Option B: Manual (GitHub UI)

  1. Go to: https://github.com/Abeshith/RAG/actions
  2. Click "Deploy to Hugging Face Spaces" workflow
  3. Click "Run workflow" → "Run workflow"

Step 6: Monitor Deployment

  1. Watch GitHub Actions:

    • Go to: https://github.com/Abeshith/RAG/actions
    • Click the running workflow
    • Monitor progress through 3 stages:
      • ✅ Stage 1: Test Application (~2-3 min)
      • ✅ Stage 2: Build Docker Image (~3-5 min)
      • ✅ Stage 3: Deploy to HF Spaces (~1 min)

  2. Watch Hugging Face Build:

    • Go to your Space: https://huggingface.co/spaces/[username]/[space-name]
    • Click "Build" tab
    • Watch Docker image build (~5-10 min)
    • Status will change: Building → Running

  3. Check Application:

    • Once status is "Running", click "App" tab
    • Your chatbot should load!
    • Try uploading a document and chatting

🔍 Troubleshooting

Issue 1: GitHub Actions Fails at "Deploy to HF Spaces"

Solution: Check if all 3 GitHub secrets are set correctly:

Issue 2: HF Space Shows "Application Error"

Solution: Check if all 5 HF Space secrets are set:

  • Go to Space → Settings → Repository secrets
  • Verify all API keys are present

Issue 3: App Starts but Database Connection Fails

Solution: Verify your connection strings:

  • MongoDB URI should start with mongodb+srv:// or mongodb://
  • Redis URL should start with redis:// or rediss://
  • Qdrant URL should be the full cluster URL

Issue 4: Docker Build Fails

Solution: Check HF build logs:

  • Go to Space → Build tab → View logs
  • Common issues: Missing dependencies, syntax errors

📊 CI/CD Pipeline Stages

Stage 1: Test Application (2-3 min)

  • ✅ Checkout code
  • ✅ Install Python 3.11
  • ✅ Cache dependencies
  • ✅ Install requirements
  • ✅ Run pytest with coverage
  • ✅ Upload test results

Fails if: Tests don't pass

Stage 2: Build Docker Image (3-5 min)

  • ✅ Setup Docker Buildx
  • ✅ Build image from Dockerfile
  • ✅ Test container startup
  • ✅ Verify health check

Fails if: Docker build errors or container won't start

Stage 3: Deploy to HF Spaces (1 min)

  • ✅ Configure git
  • ✅ Verify secrets
  • ✅ Push to HF git repository
  • ✅ Trigger HF rebuild

Fails if: Secrets missing or HF authentication fails

🎯 What Happens After Deployment?

  1. Hugging Face receives your code
  2. Detects Dockerfile → Starts Docker build
  3. Builds image with all dependencies (~5-10 min)
  4. Starts container on port 7860
  5. Runs health check every 30 seconds
  6. App is live! At https://huggingface.co/spaces/[username]/[space-name]

🔄 Future Deployments

Every time you push to main branch:

  1. GitHub Actions runs automatically
  2. Tests → Build → Deploy pipeline executes
  3. HF Space automatically rebuilds
  4. New version goes live (~10-15 min total)

📝 Quick Reference

Your GitHub Repo: https://github.com/Abeshith/RAG

GitHub Actions: https://github.com/Abeshith/RAG/actions

GitHub Secrets: https://github.com/Abeshith/RAG/settings/secrets/actions

Your HF Space: https://huggingface.co/spaces/[YOUR_USERNAME]/[YOUR_SPACE_NAME]

HF Space Settings: https://huggingface.co/spaces/[YOUR_USERNAME]/[YOUR_SPACE_NAME]/settings

✅ Checklist

Before deployment, ensure:

  • HF Space created
  • HF token generated
  • 3 GitHub secrets added (HF_TOKEN, HF_USERNAME, HF_SPACE_NAME)
  • 5 HF Space secrets added (all API keys)
  • Code pushed to main branch
  • GitHub Actions workflow triggered
  • HF build completed successfully
  • App is accessible and working

🎉 Success!

Once all stages pass and HF shows "Running":

  1. Visit your Space URL
  2. Upload a document (PDF/TXT/MD)
  3. Ask questions about it
  4. Toggle RAG ON/OFF to compare responses
  5. Share your Space with others!

Need Help?