docs/deployment/huggingface.md

Deploying to Hugging Face Spaces (Docker)

This guide provides step-by-step instructions to deploy Multiverse AI Studio to Hugging Face Spaces as a monolithic Docker application.

---

🛠️ Step 1: Create a new Space on Hugging Face

1. Log in to Hugging Face.
2. Click on your profile icon in the top right and select New Space (or go directly to huggingface.co/new-space).
3. Fill in the Space settings:
   • Space Name: Multiverse-AI-Studio (or your choice).
   • License: apache-2.0 (or your choice).
   • SDK: Select Docker.
   • Docker Template: Select Blank (do not select any pre-configured template; our local Dockerfile will define the container).
   • Space Hardware: CPU Basic (Free) is sufficient for our cloud image generation and local depth maps. If you want full-speed local video/audio generation, you can upgrade to a GPU instance.
   • Visibility: Public or Private.
4. Click Create Space.

---

⚙️ Step 2: Configure Environment Secrets

Because the pipeline requires access tokens and production flags, you must inject these variables into the Space's runtime environment:

1. In your newly created Space, navigate to the Settings tab.
2. Scroll down to the Variables and secrets section.
3. Click New secret to add the following credentials:
   • HF_TOKEN: Paste your Hugging Face User Access Token (needed for FLUX cloud queries and model downloads).
   • MOCK_INFERENCE: Set to False (to run the real production cloud FLUX image generation and local depth mapping).
   • FORCE_CPU_INFERENCE: Set to False (safe default to keep audio/video mock compilation on basic CPU instances to avoid memory crash, or set to True if you want to test CPU-only execution of all models).
4. Save the secrets.

---

🚀 Step 3: Push Your Code to the Space

Hugging Face Spaces are backed by a Git repository. You can push your code directly to the Space's Git remote:

Option A: Push directly from your local repository (Recommended)

You can add your Hugging Face Space as a new git remote and push directly to it:

1. Open your terminal in the project root directory.
2. Add the Hugging Face remote (replace <username> and <space-name> with your HF details):

   git remote add hf https://huggingface.co/spaces/<username>/<space-name>
   

3. Push to Hugging Face:

   # You will be prompted for your Hugging Face username and token (use your HF_TOKEN as the password)
   git push -f hf main
   

Option B: Clone and Copy

If you prefer to keep the repositories separate:

1. Clone the empty Hugging Face Space repository:

   git clone https://huggingface.co/spaces/<username>/<space-name>
   

2. Copy all files from your Multiverse_AI_Studio folder (except .git, .env, and node_modules/) into the cloned directory.
3. Commit and push the files:

   git add .
   git commit -m "Deploy Multiverse AI Studio monolithic container"
   git push
   

---

🔍 Step 4: Build and Verify

1. Go to your Hugging Face Space page.
2. You will see the status change to Building as it executes the Dockerfile steps:
   • It builds the React client.
   • It sets up the Debian/Python image, installs system requirements (libsndfile, FFmpeg).
   • It starts the uvicorn web server.
3. Once the build finishes, the status will show Running, and the app will load directly inside the Hugging Face Space iframe!