DEPLOYMENT_GUIDE.md

Hugging Face Spaces Deployment Guide

This guide walks you through deploying the RAG system to Hugging Face Spaces for free, permanent hosting.

Prerequisites

• Hugging Face account (sign up here)
• Git installed on your local machine
• Code migrated to use HF Inference API (already done ✅)

Step 1: Test Locally (Recommended)

Before deploying, test the application with HF Inference API locally:

1.1 Get Your HF Token

1. Go to https://huggingface.co/settings/tokens
2. Click "New token"
3. Name it (e.g., "RAG System")
4. Select read permissions
5. Click "Generate"
6. Copy the token (starts with hf_)

1.2 Set Environment Variable

# Linux/Mac
export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Windows (PowerShell)
$env:HF_TOKEN="hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

1.3 Install Dependencies

cd /Users/v.hirenko/Desktop/DevHubVault/my-ai-projects/rag-python-rag
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt

1.4 Run Tests

python test_hf_integration.py

If all tests pass, proceed to deployment!

1.5 Test the Application

python app.py

Open http://localhost:7860 and test with a few questions.

Step 2: Create Hugging Face Space

2.1 Create New Space

1. Go to https://huggingface.co/new-space
2. Fill in the details:
   • Owner: Your username (e.g., monsara)
   • Space name: rag-python-rag
   • License: MIT
   • Select the Space SDK: Gradio
   • Space hardware: CPU basic (free)
   • Space visibility: Public (or Private if you prefer)
3. Click "Create Space"

2.2 Note Your Space URL

Your Space will be available at:

https://huggingface.co/spaces/YOUR_USERNAME/rag-python-rag

Step 3: Configure Space Secrets

3.1 Add HF_TOKEN Secret

1. Go to your Space page
2. Click on "Settings" (gear icon)
3. Scroll down to "Repository secrets"
4. Click "Add a secret"
5. Fill in:
   • Name: HF_TOKEN
   • Value: Your HF token from Step 1.1
6. Click "Add"

⚠️ Important: The Space will NOT work without this secret!

Step 4: Push Code to Space

You have two options:

Option A: Direct Git Push (Recommended)

cd /Users/v.hirenko/Desktop/DevHubVault/my-ai-projects/rag-python-rag

# Add HF Space as remote
git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/rag-python-rag
# Replace YOUR_USERNAME with your actual HF username

# Push to HF Space
git push hf main

If prompted for credentials:

• Username: Your HF username
• Password: Your HF token (the same one you created)

Option B: Link GitHub Repository

1. In your Space Settings
2. Find "Linked repositories"
3. Click "Link a GitHub repository"
4. Select monsara/rag-python-rag
5. The Space will automatically sync with your GitHub repo

Step 5: Verify Deployment

5.1 Check Build Logs

1. Go to your Space page
2. Click on "Logs" tab
3. Watch the build process
4. Look for:

   ✅ HF_TOKEN validated successfully
   ✅ RAG pipeline setup complete!
   Running on local URL:  http://0.0.0.0:7860
   

5.2 Test the Space

1. Once "Running" status appears
2. Click on the Space URL
3. Try example questions
4. Verify answers are generated correctly

Step 6: Update README (Optional)

Replace the Space README with the HF-specific one:

cd /Users/v.hirenko/Desktop/DevHubVault/my-ai-projects/rag-python-rag

# Backup current README
mv README.md README_LOCAL.md

# Use HF README
cp README_HF.md README.md

# Commit and push
git add README.md
git commit -m "Update README for HF Spaces"
git push hf main

Troubleshooting

Issue: "HF_TOKEN not found"

Solution: Make sure you added HF_TOKEN to Space secrets (Step 3.1)

Issue: "Model not found" or "Rate limit exceeded"

Solution:

• Check if you're using the correct model name in config.py
• Free tier has rate limits (~1000 requests/hour)
• Consider upgrading to HF Pro ($9/month)

Issue: "Build failed"

Solution:

1. Check the build logs for specific errors
2. Verify requirements.txt has all dependencies
3. Make sure Python version is compatible (3.9+)

Issue: "Application crashes on startup"

Solution:

1. Check if app.py is set as the entry point in Space settings
2. Verify all imports are correct
3. Check logs for Python errors

Issue: Slow responses

Solution:

• Free tier uses shared infrastructure
• Upgrade to better hardware (paid)
• Or optimize chunk size and retrieval count

Monitoring

View Logs

# Real-time logs
# Go to Space page → Logs tab

Check Usage

1. Go to your HF profile
2. Click on "Usage & billing"
3. View API usage statistics

Updating the Space

Update Code

cd /Users/v.hirenko/Desktop/DevHubVault/my-ai-projects/rag-python-rag

# Make your changes
git add .
git commit -m "Your update message"
git push hf main

The Space will automatically rebuild.

Update Dependencies

Edit requirements.txt, then:

git add requirements.txt
git commit -m "Update dependencies"
git push hf main

Update Configuration

Edit config.py, then push changes as above.

Cost Considerations

Free Tier (Current Setup)

• ✅ Cost: $0/month
• ✅ Hosting: Unlimited
• ⚠️ Rate limits: ~1000 requests/hour
• ⚠️ Performance: Shared CPU
• ⚠️ Tokens: 1024 max per response

Upgrade Options

HF Pro ($9/month):

• Higher rate limits
• Faster inference
• Priority support
• Better hardware options

Dedicated Hardware:

• CPU Upgrade: $0.03/hour (~$22/month)
• GPU T4: $0.60/hour (~$432/month)
• GPU A10G: $1.05/hour (~$756/month)

Security Best Practices

1. Never commit HF_TOKEN to Git
2. Use Space secrets for all sensitive data
3. Rotate tokens periodically
4. Monitor usage for unexpected spikes
5. Set rate limits in your application

Next Steps

After successful deployment:

1. ✅ Test thoroughly with various questions
2. ✅ Share the Space URL with users
3. ✅ Monitor logs for errors
4. ✅ Gather user feedback
5. ✅ Iterate and improve

Support

If you need help:

1. Check HF Spaces documentation
2. Visit HF Community forums
3. Open an issue on GitHub

---

Quick Reference

Space URL: https://huggingface.co/spaces/YOUR_USERNAME/rag-python-rag

Settings: https://huggingface.co/spaces/YOUR_USERNAME/rag-python-rag/settings

Logs: https://huggingface.co/spaces/YOUR_USERNAME/rag-python-rag/logs

Push command:

git push hf main

Update secret: Space Settings → Repository secrets → Edit

---

Good luck with your deployment! 🚀