HUGGINGFACE_DEPLOY.md

Deploying to Hugging Face Spaces

This guide will help you deploy Video Genesis Studio to Hugging Face Spaces.

Prerequisites

1. Hugging Face Account

   • Sign up at https://huggingface.co/join
   • Verify your email

2. API Keys

   • KIE API Key (required): https://kie.ai/api-key
   • Optional: Gemini, OpenAI, Replicate keys

3. GitHub Repository

   • Your code should be in a GitHub repository
   • Or you can upload directly to Hugging Face

Step-by-Step Deployment

Option 1: Deploy from GitHub (Recommended)

1. Prepare Your Repository:

   # Make sure Dockerfile.hf is in the root
   # Make sure README_HF.md exists (or rename it to README.md)
   git add Dockerfile.hf README_HF.md
   git commit -m "Add Hugging Face deployment files"
   git push
   

2. Create a New Space:

   • Go to https://huggingface.co/spaces
   • Click "Create new Space"
   • Fill in:
     • Space name: video-genesis-studio (or your choice)
     • SDK: Select Docker
     • Visibility: Public or Private
     • Hardware: CPU Basic (free) or upgrade for better performance
   • Click "Create Space"

3. Connect Repository:

   • In Space settings, go to "Repository" tab
   • Click "Connect to GitHub"
   • Select your repository
   • Set Dockerfile path: Dockerfile.hf
   • Save

4. Set Environment Variables:

   • Go to "Variables and secrets" tab
   • Add the following required variables:

     KIE_API_KEY=your_kie_api_key_here
     VITE_API_BASE_URL=https://your-username-video-genesis-studio.hf.space
     ENVIRONMENT=production
     ALLOWED_USERS=admin:your-secure-password,user1:password123
     JWT_SECRET_KEY=your-very-secure-random-secret-key-minimum-32-chars
     

   • Authentication Setup (Required):
     • ALLOWED_USERS: Format is username1:password1,username2:password2
     • JWT_SECRET_KEY: Generate a secure random key (see AUTH_SETUP.md)
   • Optional variables:

     VITE_GEMINI_API_KEY=your_gemini_key
     OPENAI_API_KEY=your_openai_key
     REPLICATE_API_TOKEN=your_replicate_token
     

   • Click "Save" after adding each variable

   Note: See AUTH_SETUP.md for detailed authentication configuration.

5. Build Arguments:

   • Go to "Settings" → "Build arguments"
   • Add:

     VITE_API_BASE_URL=https://your-username-video-genesis-studio.hf.space
     

   • This ensures the frontend knows the correct API URL

6. Deploy:

   • Hugging Face will automatically build and deploy
   • Watch the build logs in the "Logs" tab
   • Wait for "Your Space is live!" message

Option 2: Upload Directly to Hugging Face

1. Create Space:

   • Go to https://huggingface.co/spaces
   • Click "Create new Space"
   • Select Docker SDK
   • Create the Space

2. Clone and Upload:

   # Clone your Hugging Face Space
   git clone https://huggingface.co/spaces/your-username/video-genesis-studio
   cd video-genesis-studio
   
   # Copy your files
   cp -r /path/to/your/project/* .
   
   # Make sure Dockerfile.hf is named correctly
   # Rename README_HF.md to README.md
   mv README_HF.md README.md
   
   # Commit and push
   git add .
   git commit -m "Initial deployment"
   git push
   

3. Set Environment Variables (same as Option 1, step 4)

Configuration

Space Settings

1. Hardware:

   • CPU Basic (Free): Good for testing, limited resources
   • CPU Upgrade ($0.60/hour): Better performance
   • GPU (if needed): For heavy video processing

2. Storage:

   • Default: 50GB
   • Upgrade if you need more for video storage

3. Environment Variables:

   • Set in "Variables and secrets" tab
   • Required: KIE_API_KEY
   • Recommended: VITE_API_BASE_URL (your Space URL)

Build Configuration

The Dockerfile.hf is configured to:

• Build React frontend with correct API URL
• Install Python dependencies
• Install FFmpeg for video processing
• Serve on port 7860 (Hugging Face default)

Frontend Configuration

The frontend is built with VITE_API_BASE_URL pointing to your Space URL. This is set via:

• Build argument in Dockerfile
• Environment variable during build

Verifying Deployment

1. Check Build Logs:

   • Go to "Logs" tab in your Space
   • Look for successful build messages
   • Check for any errors

2. Test Health Endpoint:

   • Visit: https://your-space.hf.space/health
   • Should return JSON with status "healthy"

3. Test Frontend:

   • Visit: https://your-space.hf.space
   • Should load the React application

4. Test API Docs:

   • Visit: https://your-space.hf.space/docs
   • Should show Swagger UI

Troubleshooting

Build Fails

Issue: Build fails with npm errors

• Solution: Check that frontend/package.json exists and is valid
• Check build logs for specific error messages

Issue: Frontend build fails

• Solution: Ensure VITE_API_BASE_URL is set correctly
• Check that all frontend dependencies are in package.json

App Not Loading

Issue: Frontend shows blank page

• Solution:
  • Check browser console for errors
  • Verify VITE_API_BASE_URL matches your Space URL
  • Check that frontend was built successfully (check logs)

Issue: API calls fail

• Solution:
  • Verify KIE_API_KEY is set correctly
  • Check API logs in Space logs
  • Ensure CORS is configured (already set to allow all)

Port Issues

Issue: App doesn't start

• Solution:
  • Hugging Face uses port 7860 by default
  • The Dockerfile is configured to use PORT env var
  • Check logs for port binding errors

Storage Issues

Issue: Videos not saving

• Solution:
  • Check storage directory permissions
  • Verify storage path exists
  • Check available disk space

Updating Your Space

1. Make Changes:

   # Make your code changes
   git add .
   git commit -m "Update app"
   git push
   

2. Hugging Face Auto-Rebuilds:

   • Spaces automatically rebuild on push
   • Watch the logs for build progress

3. Manual Rebuild:

   • Go to Space settings
   • Click "Rebuild" if needed

Environment Variables Reference

Variable	Required	Description
KIE_API_KEY	Yes	KIE API key for video generation
ALLOWED_USERS	Yes	User credentials: username1:pass1,username2:pass2
JWT_SECRET_KEY	Yes	Secure random key for JWT signing (min 32 chars)
VITE_API_BASE_URL	Recommended	Your Space URL (for frontend)
ENVIRONMENT	No	Set to production
VITE_GEMINI_API_KEY	No	Gemini API key
OPENAI_API_KEY	No	OpenAI API key
REPLICATE_API_TOKEN	No	Replicate API token
PORT	Auto	Set by Hugging Face (7860)

Cost Considerations

• Free Tier: CPU Basic, 50GB storage
• Paid Tiers:
  • CPU Upgrade: $0.60/hour
  • GPU options available
• Storage: Additional storage can be purchased

Security Notes

1. API Keys:

   • Never commit API keys to your repository
   • Use Hugging Face's "Variables and secrets" feature
   • Keys are encrypted and only accessible to your Space

2. CORS:

   • Currently set to allow all origins
   • For production, consider restricting to your domain

3. Rate Limiting:

   • Consider implementing rate limiting for public Spaces
   • Monitor API usage

Authentication

Your app now requires login! See AUTH_SETUP.md for:

• Setting up user credentials
• Configuring JWT secret key
• Managing multiple users
• Security best practices

Quick Setup:

1. Set ALLOWED_USERS environment variable: admin:your-password,user1:pass1
2. Set JWT_SECRET_KEY to a secure random string (32+ characters)
3. Users will see a login page before accessing the app

Support

• Hugging Face Docs: https://huggingface.co/docs/hub/spaces
• Space Community: https://huggingface.co/spaces
• Issues: Check Space logs for errors
• Authentication: See AUTH_SETUP.md for auth configuration

Next Steps

1. ✅ Deploy your Space
2. ✅ Set environment variables (including ALLOWED_USERS and JWT_SECRET_KEY)
3. ✅ Test login functionality
4. ✅ Test the deployment
5. ✅ Share credentials with authorized users only
6. ✅ Monitor usage and performance

---

Your Video Genesis Studio is now live and secured on Hugging Face! 🚀🔒