Hugging Face's logo

Spaces:
ghmk
/
character_forge
Sleeping

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

Deploying Character Forge to HuggingFace Spaces

This guide will help you deploy Character Forge to HuggingFace Spaces.

Prerequisites

  1. HuggingFace Account: Sign up at https://huggingface.co/join
  2. Gemini API Key: Get one free at https://aistudio.google.com/app/apikey

Step-by-Step Deployment

1. Create a New Space

Go to https://huggingface.co/spaces and click "Create new Space"

Fill in the form:

  • Owner: Your username or organization
  • Space name: character_forge (or your preferred name)
  • Short description: "Transform a single image into a complete multi-angle character sheet"
  • License: GNU AGPL v3.0 ⚠️ IMPORTANT
  • Select SDK: Docker
  • Docker template: Streamlit
  • Space hardware: CPU Basic (Free) - sufficient for Gemini API backend
  • Visibility: Public or Private (your choice)

Click "Create Space"

2. Upload Files

You have two options:

Option A: Git Upload (Recommended) 

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

# Copy Character Forge files
cp -r /path/to/character_forge_release/* .

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

Option B: Web Upload

Use the HuggingFace web interface to upload:

Required files/folders:

character_forge/              # Main application directory
├── character_forge_image/    # Streamlit app
│   ├── app.py               # Main entry point
│   ├── config/              # Configuration
│   ├── services/            # Backend services
│   └── ui/                  # UI components
├── .streamlit/
│   └── config.toml          # Streamlit config
├── Dockerfile               # HuggingFace deployment config
├── requirements.txt         # Python dependencies
├── LICENSE                  # GNU AGPL v3.0
├── NOTICE                   # Important license info
└── README.md                # Documentation

3. Configure Environment Variables

This is CRITICAL for the app to work!

  1. Go to your Space settings: Settings tab
  2. Click on Repository secrets
  3. Add a new secret:
    • Name: GEMINI_API_KEY
    • Value: Your actual Gemini API key from Google AI Studio

4. Wait for Build

HuggingFace will automatically:

  1. Detect the Dockerfile
  2. Build the Docker image
  3. Deploy the application
  4. Show build logs in real-time

This takes 3-5 minutes for the first build.

5. Access Your App

Once deployed, your app will be available at:

https://huggingface.co/spaces/YOUR_USERNAME/character_forge

Configuration Details

Dockerfile

The included Dockerfile is pre-configured for HuggingFace Spaces:

  • Uses Python 3.10
  • Installs all dependencies from requirements.txt
  • Exposes port 7860 (HuggingFace standard)
  • Runs Streamlit with proper server settings

Streamlit Config

The .streamlit/config.toml file includes:

  • Port 7860 binding
  • Headless mode for server deployment
  • Disabled CORS for HuggingFace proxy
  • Custom theme matching Character Forge branding

Requirements

The requirements.txt includes minimal dependencies:

  • Streamlit for the UI
  • google-genai for Gemini API
  • Pillow for image processing
  • Other essential libraries

No GPU required - all processing happens via Gemini API!

Troubleshooting

App Won't Start

Check the build logs for errors. Common issues:

  • Missing GEMINI_API_KEY secret
  • Incorrect file paths in Dockerfile
  • Missing dependencies in requirements.txt

"Invalid API Key" Error

  1. Verify your Gemini API key at https://aistudio.google.com/app/apikey
  2. Check the secret name is exactly GEMINI_API_KEY (case-sensitive)
  3. Make sure there are no extra spaces in the key value

Slow Performance

  • Free CPU tier is slower than local GPU
  • Consider upgrading to CPU Upgrade ($0.05/hour) if needed
  • Generation still takes 30-60 seconds per image with Gemini API

Upload Size Limits

HuggingFace has file size limits. If you get errors:

  • Don't include large example images in the repo
  • Keep the deployment lean (under 500MB total)
  • Users will upload their own images

Updating Your Space

To update after changes:

cd character_forge
git pull origin main  # Get latest changes
git add .
git commit -m "Update to latest version"
git push

HuggingFace will automatically rebuild and redeploy.

Cost Considerations

HuggingFace Hosting

  • CPU Basic (Free): $0/month - Works great!
  • CPU Upgrade: $0.05/hour ($36/month if always on)
  • Sleep mode: Free tier sleeps after 48h inactivity

Gemini API Usage

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

Total cost for casual use: FREE!

License Compliance

Character Forge is licensed under GNU AGPL v3.0:

✓ Your deployment is legal - hosting on HuggingFace Spaces is fine ✓ User-generated content - Users own their generated images ✓ Must keep open source - Don't remove license files ✗ No proprietary versions - Any modifications must stay AGPL

Make sure your Space is marked as AGPL-3.0 license in settings!

Support

Ready to deploy? Follow the steps above and you'll be generating character sheets in minutes!