DEPLOY.md

Deployment Guide

HuggingFace Spaces Deployment

Prerequisites

1. HuggingFace Account: Sign up at huggingface.co
2. Git Credentials: Configure HF credentials for git push

Step 1: Create the Space

1. Go to huggingface.co/new-space

2. Fill in the details:

   • Space name: brickstyle-gen
   • License: MIT
   • Select the SDK: Gradio
   • Space hardware: CPU (free) or GPU (paid, faster)
   • Visibility: Public or Private

3. Click Create Space

Step 2: Configure Git Authentication

Option A: Using Access Token (Recommended)

# Create token at: https://huggingface.co/settings/tokens
# Select "Write" access

# Configure git to use token
git config credential.helper store

# On first push, enter:
# Username: your-hf-username
# Password: your-hf-access-token

Option B: Using SSH

# Add SSH key at: https://huggingface.co/settings/keys
ssh-keygen -t ed25519 -C "your-email@example.com"

# Update remote to use SSH
git remote remove hf
git remote add hf git@hf.co:spaces/yeungjosh/brickstyle-gen

Step 3: Push to Space

# Push all commits to HF Space
git push hf main

The Space will automatically:

1. Install dependencies from requirements.txt (~5-10 minutes)
2. Download model weights (~7GB, another 5-10 minutes)
3. Launch the Gradio app
4. Display at https://huggingface.co/spaces/yeungjosh/brickstyle-gen

Step 4: Configure Space Settings (Optional)

After deployment, you can configure the Space:

1. Go to your Space's Settings tab
2. Hardware: Upgrade to GPU for faster generation
3. Environment Variables: Add any BRICKSTYLE_* config vars
4. Sleep time: Configure auto-sleep for free tier

Deployment Status

Check build logs in your Space's Logs tab to monitor:

• Dependency installation progress
• Model download status
• App startup

First build typically takes 10-20 minutes due to model downloads.

Updating the Space

After initial deployment, updates are simple:

# Make changes locally
git add .
git commit -m "Update feature X"

# Push to both remotes
git push origin main  # GitHub
git push hf main      # HuggingFace Space

Space will rebuild automatically (faster after first build).

Troubleshooting

Build fails with memory error:

• Upgrade to a Space with more RAM
• Or reduce model size in code

"Repository not found" error:

• Ensure Space is created on HuggingFace first
• Check Space name matches remote URL
• Verify git credentials are configured

App starts but generation fails:

• Check Space logs for model download errors
• Verify sufficient disk space (needs ~10GB)
• Check environment variables are set correctly

Slow generation times:

• Free CPU Spaces are slow (30-90 sec per image)
• Upgrade to GPU hardware for 5-15 sec generation
• Consider reducing default steps in app.py

Performance by Hardware Tier

Hardware	Speed	Cost
CPU (free)	30-90 sec/image	Free
CPU Upgrade	20-40 sec/image	~$0.03/hr
T4 GPU	10-20 sec/image	~$0.60/hr
A10G GPU	5-10 sec/image	~$3.15/hr

Custom Domain (Optional)

HuggingFace Pro users can set custom domains in Space settings.

---

Alternative Deployment Options

Local Server

Run on your own machine:

python app.py
# Access at http://localhost:7860

Share publicly using Gradio's share feature:

# In app.py
demo.launch(share=True)

Gradio will provide a temporary public URL (expires after 72 hours).

Docker Deployment

# Build image
docker build -t brickstyle-gen .

# Run container
docker run -p 7860:7860 \
  -e BRICKSTYLE_ALLOW_UNSAFE=0 \
  brickstyle-gen

(Note: Requires creating a Dockerfile)

Cloud Platforms

BrickStyle-Gen can be deployed to:

• Render: Gradio support, free tier available
• Railway: Good GPU options
• AWS/GCP: Full control, higher cost

See each platform's Gradio deployment guides for instructions.