DEPLOY.md

# Deployment Guide

## HuggingFace Spaces Deployment

### Prerequisites

1. **HuggingFace Account**: Sign up at [huggingface.co](https://huggingface.co/join)
2. **Git Credentials**: Configure HF credentials for git push

### Step 1: Create the Space

1. Go to [huggingface.co/new-space](https://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)

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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:

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

Share publicly using Gradio's share feature:

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

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

### Docker Deployment

```bash
# 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.