File size: 4,766 Bytes
59ce7b1 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 |
# 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:
```yaml
---
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)
```bash
# 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
```bash
# 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:
```bash
# .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](docker.md)
- [MCP Integration](mcp-integration.md)
- [Configuration Reference](../reference/configuration.md)
|