Hugging Face's logo

Spaces:
ghmk
/
character_forge
Sleeping

App Files Community
character_forge / docs /HUGGINGFACE_DEPLOYMENT.md
ghmk's picture
ghmk
Initial deployment of Character Forge
5b6e956
preview code
|
raw
history blame contribute delete
5.62 kB

HuggingFace Spaces Deployment Guide

This guide will walk you through deploying Character Forge to HuggingFace Spaces.

Prerequisites

Deployment Steps

1. Create a New Space

  1. Go to https://huggingface.co/spaces
  2. Click "Create new Space"
  3. Configure your space:
    • Name: character-forge (or your preferred name)
    • License: Apache 2.0
    • SDK: Streamlit
    • Hardware: CPU Basic (free tier works fine)
  4. Click "Create Space"

2. Upload Files

You have two options:

Option A: Git Clone (Recommended) 

# Clone your new space
git clone https://huggingface.co/spaces/YOUR_USERNAME/character-forge
cd character-forge

# Copy all files from character_forge_release directory
cp -r /path/to/character_forge_release/* .

# Add and commit
git add .
git commit -m "Initial commit: Character Forge deployment"
git push

Option B: Web Upload

  1. Click "Files and versions" in your Space
  2. Click "Add file" → "Upload files"
  3. Upload all files from the character_forge_release directory
  4. Commit the changes

3. Configure Secrets

Your Gemini API key must be stored securely as a secret:

  1. Go to your Space settings
  2. Click "Repository secrets"
  3. Add a new secret:
    • Name: GEMINI_API_KEY
    • Value: Your Gemini API key (starts with AIzaSy...)
  4. Save the secret

4. Wait for Build

HuggingFace will automatically:

  • Install dependencies from requirements.txt
  • Install system packages from packages.txt
  • Start your Streamlit app

This takes 2-5 minutes.

5. Test Your Space

Once built, your Space will be available at:

https://huggingface.co/spaces/YOUR_USERNAME/character-forge

Configuration Options

Hardware Upgrades

For better performance:

  • CPU Basic (free): Good for testing, slower generations
  • CPU Upgrade ($0.03/hour): Faster, recommended for public spaces
  • GPU: Not needed for Gemini API backend

Environment Variables

You can add more environment variables in Repository Secrets if needed:

  • GEMINI_API_KEY: Your Google Gemini API key (required)
  • Any other custom configuration

Custom Domain (Pro users)

HuggingFace Pro users can set up custom domains in Space settings.

Troubleshooting

Build Fails

Check logs:

  1. Go to "App" tab in your Space
  2. Click "Logs" at the bottom
  3. Look for error messages

Common issues:

  • Missing dependencies: Add to requirements.txt
  • System packages: Add to packages.txt
  • Import errors: Check file paths in code

API Key Not Working

Verify secret:

  1. Go to Repository secrets
  2. Check GEMINI_API_KEY is set correctly
  3. Restart the space (Settings → Factory reboot)

Test manually:

  • Enter API key in the UI sidebar
  • Check if it works there

App Not Starting

Check logs for:

  • Import errors
  • Missing files
  • Configuration issues

Try:

  1. Factory reboot (Settings → Factory reboot)
  2. Check all files are uploaded
  3. Verify app.py is in root directory

Slow Performance

Free tier limitations:

  • CPU Basic is slower
  • Consider CPU Upgrade for production

Optimize:

  • Use temperature 0.3-0.4 for faster results
  • Smaller image sizes when possible

Making Your Space Public

Privacy Settings

  1. Go to Space settings
  2. Choose visibility:
    • Public: Anyone can view and use
    • Private: Only you can access

Usage Limits

To prevent abuse on public spaces:

  1. Add rate limiting (code already included)
  2. Monitor usage in Space analytics
  3. Consider requiring sign-in for high usage

Sharing

Share your Space:

  • Direct link: https://huggingface.co/spaces/YOUR_USERNAME/character-forge
  • Embed widget: Available in Space settings
  • Duplicate: Others can duplicate to their account

Updating Your Space

Via Git 

cd character-forge
# Make your changes
git add .
git commit -m "Update: description"
git push

Via Web

  1. Go to "Files and versions"
  2. Edit files directly or upload new versions
  3. Commit changes

Cost Estimation

HuggingFace Costs

  • CPU Basic: Free
  • CPU Upgrade: ~$0.03/hour (when running)
  • Persistent storage: Free up to 50GB

Gemini API Costs

  • ~$0.03 per image generation
  • Character sheet: ~$0.15 (5 images)
  • Free tier: 15 requests/minute

Total Cost Example

Public space with 100 users/day:

  • HF Space (CPU Upgrade, 24/7): ~$21.60/month
  • Gemini API: Varies by usage
    • Light: 100 images/day = ~$90/month
    • Heavy: 1000 images/day = ~$900/month

Recommendation: Start with free tier, upgrade as needed.

Best Practices

Security

  • ✅ Store API keys in Repository Secrets
  • ✅ Never commit secrets to git
  • ✅ Use environment variables for configuration
  • ❌ Don't hardcode API keys in code

Performance

  • ✅ Use caching where possible (Streamlit @st.cache_data)
  • ✅ Optimize image sizes
  • ✅ Set reasonable timeout limits
  • ❌ Don't store large files in git

User Experience

  • ✅ Add clear instructions in UI
  • ✅ Show helpful error messages
  • ✅ Provide examples
  • ❌ Don't assume users know how to use it

Support

Need help?

Next Steps

After deployment:

  1. ✅ Test all features
  2. ✅ Share with users
  3. ✅ Monitor logs and usage
  4. ✅ Collect feedback
  5. ✅ Iterate and improve

Good luck with your deployment! 🚀