website/docs/deployment/huggingface-spaces.md

metadata

sidebar_position: 4

Hugging Face Spaces Deployment

Complete guide to deploy Open Navigator to Hugging Face Spaces with all three applications running together.

📋 What Gets Deployed

This deployment runs all three apps in a single Docker Space:

Component	Access Path	Description
Documentation	/docs	Docusaurus documentation site
Main App	/	React frontend application
API	/api	FastAPI backend server

All served through nginx reverse proxy on port 7860 (Hugging Face Spaces default).

🚀 Quick Start for Developers

TL;DR - Deploy in 3 commands:

# 1. Set your Hugging Face username in .env
echo "HF_USERNAME=your_username" >> .env

# 2. Run the deployment script (includes testing)
./deploy-huggingface.sh

# 3. Configure your Space
# - Go to https://huggingface.co/spaces/YOUR_USERNAME/www.communityone.com
# - Settings → Resource configuration → Select "CPU Basic"
# - Settings → Variables and secrets → Add your API keys

The script will:

1. ✅ Test Docusaurus build (catches config errors)
2. ✅ Test Docker build locally (validates deployment)
3. ✅ Create the Space on Hugging Face
4. ✅ Push your code
5. ✅ Trigger automatic build (~10-15 minutes)

Note: This project uses Apache 2.0 license (updated from MIT in April 2026).

💰 Cost Breakdown

Required:

• CPU Basic Hardware: ~$0.03/hour = ~$22/month
  • 2 vCPU, 16 GB RAM
  • Required to run Docker Spaces

Optional:

• Pro Plan: $9/month
  • Persistent storage (keeps data between restarts)
  • Better performance
  • Private Spaces option
  • Longer timeout limits

Total Cost: $22-31/month depending on plan

🛠️ Prerequisites

1. Hugging Face Account: Sign up at huggingface.co
2. Hugging Face Token: Create at Settings → Access Tokens
   • Needs write permission
3. API Keys: Your OpenAI/Anthropic keys for LLM features
4. Git: Installed locally

📦 Step 1: Prepare Your Repository

The deployment files are already created:

.huggingface/
  ├── README.md              # Space description (shown on HF)
  ├── nginx.conf             # Reverse proxy config
  ├── supervisord.conf       # Process manager config
  └── start.sh               # Startup script
Dockerfile.huggingface       # Multi-stage Docker build

🚀 Step 2: Create the Hugging Face Space

Option A: Using the Web UI

1. Go to huggingface.co/new-space
2. Configure:
   • Space name: open-navigator-for-engagement
   • License: Apache 2.0
   • Space SDK: Select Docker
   • Visibility: Public or Private
3. Click Create Space

Option B: Using the CLI

# Install huggingface-hub
pip install huggingface-hub

# Login with your token
huggingface-cli login

# Create the Space
huggingface-cli repo create open-navigator-for-engagement --type space --space-sdk docker

📤 Step 3: Deploy Your Code

Option A: Automated Deployment (Recommended)

Use the deployment script for easy one-command deployment:

Step 1: Set your username

Add to your .env file:

echo "HF_USERNAME=your_hf_username" >> .env

Or export for current session:

export HF_USERNAME=getcommunityone  # Replace with your username

Step 2: Run deployment script

./deploy-huggingface.sh

The script automatically:

• Creates the Space on Hugging Face
• Sets up deployment branch
• Configures Dockerfile and README
• Pushes to Hugging Face

You can also pass username as argument: ./deploy-huggingface.sh YOUR_USERNAME

Option B: Manual Deployment

If you prefer manual control:

# Add Hugging Face as a remote
git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/open-navigator-for-engagement

# Create a deployment branch with the right Dockerfile
git checkout -b huggingface-deploy

# Rename Dockerfile.huggingface to Dockerfile (HF looks for this)
cp Dockerfile.huggingface Dockerfile

# Copy the HF README to root (HF displays this)
cp .huggingface/README.md README_HF.md

# Commit changes
git add Dockerfile README_HF.md .huggingface/
git commit -m "Configure Hugging Face Space deployment"

# Push to Hugging Face
git push hf huggingface-deploy:main

🔧 Step 4: Configure Space Settings

1. Go to your Space: https://huggingface.co/spaces/YOUR_USERNAME/open-navigator-for-engagement
2. Click Settings
3. Under Resource configuration:
   • Select CPU Basic (minimum required)
   • Or CPU Upgrade for better performance
4. Under Variables and secrets (⚠️ IMPORTANT):
   • Add your API keys as secrets:

     OPENAI_API_KEY = sk-your-key-here
     ANTHROPIC_API_KEY = sk-ant-your-key-here
     HUGGINGFACE_TOKEN = hf_your-token-here
     

   • Set environment variables:

     LOG_LEVEL = INFO
     PYTHONUNBUFFERED = 1
     

5. Click Save

🔄 Step 5: Wait for Build

The Space will automatically build when you push. This takes 10-15 minutes:

1. Building documentation (Docusaurus)
2. Building frontend (React + Vite)
3. Installing Python dependencies
4. Configuring nginx reverse proxy
5. Starting services

Watch build progress in the Logs tab.

✅ Step 6: Verify Deployment

Once built, test each component:

1. Check Main App

https://YOUR_USERNAME-open-navigator-for-engagement.hf.space/

Should show the React dashboard.

2. Check Documentation

https://YOUR_USERNAME-open-navigator-for-engagement.hf.space/docs

Should show Docusaurus docs.

3. Check API

https://YOUR_USERNAME-open-navigator-for-engagement.hf.space/api/docs

Should show FastAPI Swagger docs.

4. Test API Endpoint

curl https://YOUR_USERNAME-open-navigator-for-engagement.hf.space/api/health

Should return: {"status": "healthy"}

🔄 Updating Your Space

When you make changes to your code:

# Make your changes in your main branch
git checkout main
# ... make edits ...
git commit -am "Update feature X"

# Merge to deployment branch
git checkout huggingface-deploy
git merge main

# Update Dockerfile if needed
cp Dockerfile.huggingface Dockerfile
git add Dockerfile
git commit -m "Update deployment"

# Push to Hugging Face
git push hf huggingface-deploy:main

The Space will automatically rebuild.

🐛 Troubleshooting

Build Fails

Check logs: Click Logs tab in your Space

Common issues:

• Missing dependencies → Check requirements.txt
• Node.js build errors → Check package.json versions
• Out of memory → Upgrade to larger hardware

App Doesn't Start

1. Check environment variables are set
2. Verify API keys are correct
3. Check logs for Python errors
4. Ensure port 7860 is exposed

404 Errors

• / works but /docs doesn't → Check nginx.conf routing
• /api returns 404 → Check FastAPI is running on port 8000
• Static files not loading → Check build output directories

Performance Issues

• Slow response: Upgrade to CPU Upgrade or GPU
• Timeouts: Enable Pro plan for longer limits
• Out of memory: Reduce concurrent workers or upgrade hardware

📊 Monitoring

View Logs

Settings → Logs → Container logs

Check Resource Usage

Settings → Resource configuration → Usage metrics

Monitor API Calls

FastAPI automatically logs requests to /var/log/supervisor/api.log

🔒 Security Best Practices

Secrets Management

✅ DO:

• Add API keys in Space Settings → Variables and secrets
• Use Secrets (encrypted), not Variables for sensitive data
• Set secrets as "Private" in settings

❌ DON'T:

• Commit .env files with real keys
• Hardcode secrets in code
• Share your Space's API keys

Access Control

• Set Space to Private if using sensitive data
• Use Hugging Face OAuth for user authentication
• Enable rate limiting in FastAPI

💡 Optimization Tips

Reduce Build Time

1. Use smaller Docker base images
2. Cache npm dependencies
3. Use multi-stage builds (already configured)

Improve Performance

1. Enable gzip compression (already configured in nginx)
2. Set cache headers for static assets (already configured)
3. Use CDN for large static files

Save Costs

1. Use CPU Basic instead of GPU (unless you need it)
2. Set Sleep timeout for inactive Spaces
3. Use Persistent storage only if needed (requires Pro)

🎯 Advanced: Custom Domain

Hugging Face Spaces supports custom domains:

1. Go to Space Settings
2. Under Custom domain
3. Add your domain (e.g., opennavigator.org)
4. Configure DNS:

   CNAME record: opennavigator.org → YOUR_USERNAME-open-navigator-for-engagement.hf.space
   

📚 Additional Resources

• Hugging Face Spaces Documentation
• Docker Spaces Guide
• Space Configuration

🆘 Getting Help

• Hugging Face Discord: hf.co/join/discord
• GitHub Issues: Your repo issues
• Space Discussions: Comment on your Space page

---

🎉 Next Steps

After deployment:

1. ✅ Test all three apps thoroughly
2. ✅ Share your Space URL with users
3. ✅ Monitor usage and costs
4. ✅ Set up persistent storage if needed (Pro plan)
5. ✅ Configure custom domain (optional)

Your Space URL:

https://huggingface.co/spaces/YOUR_USERNAME/open-navigator-for-engagement

Enjoy your fully deployed civic engagement platform! 🚀