docs/deployment/huggingface-spaces.md

HuggingFace Spaces Deployment

Last Updated: 2025-12-06

This guide covers deploying DeepBoner to HuggingFace Spaces.

Overview

DeepBoner is deployed to HuggingFace Spaces at: https://huggingface.co/spaces/MCP-1st-Birthday/DeepBoner

The Space runs the Gradio UI with MCP server support.

Space Configuration

The Space is configured via the README.md frontmatter:

---
title: DeepBoner
emoji: 🍆
colorFrom: pink
colorTo: purple
sdk: gradio
sdk_version: "6.0.1"
python_version: "3.11"
app_file: src/app.py
pinned: true
license: apache-2.0
short_description: "Deep Research Agent for the Strongest Boners"
tags:
  - mcp-hackathon
  - agents
  - sexual-health
  - pydantic-ai
  - pubmed
---

Deployment Methods

Method 1: Git Push (Recommended)

# Add HuggingFace remote
git remote add hf https://huggingface.co/spaces/MCP-1st-Birthday/DeepBoner

# Push to HuggingFace
git push hf main

Method 2: HuggingFace Hub

Use the HuggingFace web interface to sync with GitHub.

Secrets Configuration

Configure secrets in Space Settings → Variables and secrets:

Secret	Purpose	Required
HF_TOKEN	HuggingFace API token	Yes
NCBI_API_KEY	Higher PubMed rate limits	No
OPENAI_API_KEY	Premium mode (if offered)	No

Setting Secrets

1. Go to Space Settings
2. Click "Variables and secrets"
3. Add each secret:
   • Name: HF_TOKEN
   • Value: hf_... (your token)
   • Click "Add"

Important: Use Secrets (not Variables) for API keys - secrets are hidden.

Build Process

When you push to HuggingFace:

1. Space detects changes
2. Builds from Dockerfile (if present) or requirements.txt
3. Installs dependencies
4. Starts the application

Build logs are visible in the Logs tab.

Collaboration Workflow

Branch Strategy

GitHub (source of truth)
├── main          - Production, synced to HF
└── dev           - Development integration

HuggingFace
├── main          - Production (from GitHub)
└── yourname-dev  - Personal dev branches

Guidelines

• DO NOT push directly to main on HuggingFace
• Use personal dev branches: yourname-dev
• GitHub is the source of truth for code review
• Sync production from GitHub only

Personal Development

# Create your dev branch on HuggingFace
git checkout -b myname-dev
git push hf myname-dev

# Test on your branch
# Space will build from your branch if you switch to it

Environment Differences

Local vs Spaces

Aspect	Local	HuggingFace Spaces
API Keys	.env file	Secrets
Storage	Persistent	Ephemeral
Port	7860	Assigned
Memory	Unlimited	Limited (based on tier)

Handling Ephemeral Storage

ChromaDB data is not persisted on Space restart. For production use cases requiring persistence:

1. Use external database
2. Accept regeneration on restart
3. Consider paid Spaces with persistent storage

Hardware Tiers

HuggingFace Spaces offers different hardware:

Tier	CPU	RAM	GPU	Cost
Free	2	16GB	None	Free
CPU Basic	2	16GB	None	$0.03/hr
CPU Upgrade	8	32GB	None	$0.07/hr
T4 Small	4	15GB	T4	$0.60/hr

DeepBoner runs on Free tier but benefits from CPU Upgrade for:

• Faster embedding generation
• More concurrent users

Monitoring

Logs

View logs in the Logs tab:

• Build logs (during deployment)
• Application logs (runtime)

Health

Check Space status:

• Green: Running
• Yellow: Building
• Red: Error

Troubleshooting

Build fails

1. Check Build Logs tab
2. Common issues:
   • Invalid requirements.txt
   • Missing files
   • Syntax errors in config

App crashes on start

1. Check Application Logs
2. Common issues:
   • Missing secrets
   • Import errors
   • Memory limits

Slow performance

1. Check if on Free tier
2. Consider CPU Upgrade
3. Optimize model loading

Space sleeping

Free Spaces sleep after inactivity:

• Wake time: 30-60 seconds
• Consider "pinned" for popular Spaces

Git Hooks

To prevent accidental pushes to protected branches:

# .git/hooks/pre-push
#!/bin/bash
protected_branches=("main" "dev")
current_branch=$(git rev-parse --abbrev-ref HEAD)
remote="$1"

if [[ "$remote" == "hf" || "$remote" == "huggingface" ]]; then
  for branch in "${protected_branches[@]}"; do
    if [[ "$current_branch" == "$branch" ]]; then
      echo "Direct push to $branch on HuggingFace is not allowed."
      exit 1
    fi
  done
fi

Related Documentation

• Docker Deployment
• MCP Integration
• Configuration Reference