space_config.md

Hugging Face Spaces Deployment Guide 🤗

Quick Deployment Steps

Step 1: Create a New Space

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Enter Space name: graph-rag-chatbot
4. Select Owner: Your username
5. License: MIT (or your preference)
6. Space SDK: Docker
7. Visibility: Public (or Private)
8. Click "Create Space"

Step 2: Upload Files

After creation, clone the Space:

git clone https://huggingface.co/spaces/YOUR_USERNAME/graph-rag-chatbot
cd graph-rag-chatbot

# Copy all project files into this directory
cp -r /path/to/local/project/* .

# Add and commit
git add .
git commit -m "Initial Graph RAG chatbot deployment"
git push

The Space will automatically build and deploy once files are pushed.

Step 3: Configure Secrets

1. Go to your Space page → Settings
2. Scroll to "Repository secrets"
3. Add a new secret:
   • Name: GROQ_API_KEY
   • Value: Paste your Groq API key (from https://console.groq.com)
4. Click "Add secret"

The app will automatically use this environment variable.

Files Structure for HF Spaces

your-space-repo/
├── Dockerfile              # Docker image definition
├── app.py                  # Main Flask application
├── requirements.txt        # Python dependencies
├── .dockerignore          # Files to skip
├── templates/
│   └── index.html        # Frontend
└── README.md             # Documentation

What HF Spaces Does

1. Detects Dockerfile: Automatically reads and executes it
2. Builds Image: Installs all dependencies from requirements.txt
3. Runs Container: Starts your app on port 7860 (default HF Spaces port)
4. Injects Secrets: Environment variables are automatically available
5. Public URL: Your app is accessible at https://huggingface.co/spaces/YOUR_USERNAME/graph-rag-chatbot

Important Notes

Port Configuration

• HF Spaces automatically exposes port 7860
• Our Dockerfile and app use port 7860 ✓
• No changes needed!

Environment Variables

• HF Spaces automatically injects secrets as environment variables
• Our app reads: os.getenv('GROQ_API_KEY')
• This automatically works! ✓

Storage

• /app/data directory persists between deployments
• Uploaded files and graphs are stored here
• Note: HF Spaces has ephemeral storage by default
  • Data is cleared when Space sleeps
  • Upgrade to persistent storage if needed (paid feature)

CPU/GPU

• Free tier: 2 vCPU, 16GB RAM
• Sufficient for document processing
• Optional: Upgrade for faster embeddings

Troubleshooting HF Spaces Deployment

"App failed to build"

Check the build logs:

1. Go to Space page → Settings
2. Scroll to "Logs" section
3. Review Docker build output
4. Common issues:
   • Wrong Dockerfile syntax
   • Missing requirements
   • File paths incorrect

"App is sleeping"

• Free tier spaces sleep after inactivity
• Click the Space to wake it up
• Or upgrade to a paid GPU/CPU tier

"GROQ_API_KEY not found"

1. Verify secret is added in Space Settings
2. Restart the Space (go to Settings → Restart)
3. Wait 2-3 minutes for environment to reload

"Port connection refused"

• Ensure Dockerfile exposes port 7860
• Check EXPOSE 7860 is in Dockerfile ✓
• Check PORT=7860 in environment

Example Dockerfile for HF Spaces

Our current Dockerfile is optimized for HF Spaces:

FROM python:3.11-slim
WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y gcc g++ && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY app.py .
COPY templates/ templates/

# Create data directories
RUN mkdir -p data/uploads data/graph_data

# Set environment
ENV PORT=7860
EXPOSE 7860

# Run the app
CMD ["python", "app.py"]

✓ Ready for HF Spaces!

Monitoring and Logs

View Application Logs

1. Space page → Settings → Logs
2. Shows real-time application output
3. Useful for debugging issues

Monitor Space Health

1. Space page → Settings → Info
2. Shows CPU/RAM usage
3. Storage usage
4. Build/deployment status

Upgrade Options

1. Persistent Storage

• Free tier: 50GB ephemeral
• Paid: Unlimited persistent storage
• Price: ~$5/month

2. GPU Support

• Free tier: 2vCPU CPU
• Paid: T4 GPU ($6.50/day), A100 GPU ($9/day)
• Benefit: 10-50x faster embeddings

3. Persistent CPU

• Free tier: Sleeps after inactivity
• Paid: Always on
• Prices vary by vCPU count

Deployment Complete! 🎉

Your Graph RAG Chatbot is now live on Hugging Face Spaces!

Share your Space URL: https://huggingface.co/spaces/YOUR_USERNAME/graph-rag-chatbot

API Rate Limits (Groq)

• Free tier: 30 requests/minute
• Contact Groq for higher limits
• Implement caching to reduce API calls

Next Steps

1. Upload test documents (PDF, CSV, TXT)
2. Generate knowledge graphs
3. Test the chat functionality
4. Share your Space with others!
5. Customize styling/features as needed

---

Questions? Check the main README.md for detailed documentation.