DEPLOYMENT.md

# 🚀 Deployment Guide

This guide walks you through deploying the Colorspace Explorer to HuggingFace Spaces.

## Prerequisites

1. **HuggingFace Account**
   - Create one at https://huggingface.co/signup
   - Verify your email

2. **Git and GitHub** (optional but recommended)
   - Initialize git in your project: `git init`
   - Connect to GitHub (optional)

3. **HuggingFace CLI**
   ```bash
   pip install huggingface-hub
   huggingface-cli login
   ```

## Step 1: Test Locally

Before deploying, ensure everything works locally:

```bash
# Setup environment
./setup.sh

# Verify everything is working
python test_setup.py

# Run the app
./run.sh
```

Visit `http://localhost:8501` and test all the tabs.

## Step 2: Create a HuggingFace Space

1. Go to https://huggingface.co/spaces
2. Click **"Create new Space"**
3. Fill in the form:
   - **Owner**: Your username or organization
   - **Space name**: `colorspaces` (or your preferred name)
   - **License**: MIT (recommended)
   - **SDK**: Streamlit
   - **Visibility**: Public (recommended for educational use)
4. Click **"Create Space"**

You'll get a Space URL like: `https://huggingface.co/spaces/YOUR_USERNAME/colorspaces`

## Step 3: Deploy

### Option A: Using the Deploy Script (Recommended)

```bash
./deploy.sh
```

Follow the prompts:
- Enter your Space name (e.g., `your-username/colorspaces`)
- Confirm the commit message

The script will:
1. Add all files to git
2. Commit changes
3. Push to HuggingFace Spaces

### Option B: Manual Git Push

```bash
# Add the HuggingFace remote
git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/colorspaces

# Push to HuggingFace
git push hf main
```

## Step 4: Monitor Deployment

The Space will build and start. This usually takes 2-5 minutes.

### Check Status

```bash
# Using the script
./check_status.sh

# Or manually visit your Space URL
```

### What to expect

1. **Building** - HuggingFace installs dependencies
2. **Running** - App starts
3. **Ready** - Access your app at the Space URL

## Troubleshooting

### Build Fails - Missing Dependencies

**Error**: `ModuleNotFoundError`

**Solution**: Check `requirements.txt` is complete
```bash
pip freeze > requirements.txt
```

### Build Fails - System Dependencies

**Error**: `No module named 'cv2'` or OpenCV-related errors

**Solution**: These dependencies are in `packages.txt`. They should be installed automatically.

If not, check your `packages.txt`:
```bash
cat packages.txt
```

Should contain:
```
libgl1-mesa-glx
libglib2.0-0
```

### App Won't Start

**Error**: `Port already in use` or connection refused

**Solution**: Wait 1-2 minutes for HuggingFace to restart the app. The Space builder sometimes needs time.

### Images Not Loading

**Ensure images are committed to git:**
```bash
git add images/
git commit -m "Add sample images"
git push hf main
```

### Changes Not Showing

**Force update:**
```bash
git push hf main -f
```

Note: This force-pushes all changes. Be careful not to lose work.

## Making Updates

After deployment, to update the Space:

```bash
# Make your changes
# Edit app.py, add images, etc.

# Test locally
./run.sh

# Commit and push
git add .
git commit -m "Description of changes"
git push hf main

# The Space will automatically rebuild
```

## Performance Tips

1. **Image Sizes**: Keep images under 500px × 500px
2. **Sample Count**: Use 10-15 sample images
3. **Heavy Processing**: Consider caching with `@st.cache_resource`
4. **Memory**: Avoid loading all images at startup

## Security Considerations

1. **Sensitive Data**: Never commit API keys or passwords
2. **Check `.gitignore`**: Ensure sensitive files are ignored
3. **Public Access**: Space is public by default (OK for educational demo)

## Sharing Your Space

1. **Direct Link**: Share the Space URL
   - `https://huggingface.co/spaces/YOUR_USERNAME/colorspaces`

2. **Embed in Website**: HuggingFace provides embed code
   - Click "Share" on your Space page

3. **Education**: Reference in course materials
   - Link in syllabus, assignments, etc.

## Advanced: Custom Domain

HuggingFace Spaces Pro allows custom domains.

See: https://huggingface.co/docs/hub/spaces#custom-domains

## Support

- **HuggingFace Docs**: https://huggingface.co/docs/hub/spaces
- **Streamlit Docs**: https://docs.streamlit.io
- **Issues**: Open an issue on GitHub

## Next Steps

1. ✅ Test locally with `./run.sh`
2. ✅ Run `python test_setup.py` to verify
3. ✅ Create a HuggingFace Space
4. ✅ Deploy with `./deploy.sh`
5. ✅ Test the deployed version
6. ✅ Share the link with students!

---

**Questions?** See [README.md](README.md) or [GETTING_STARTED.md](GETTING_STARTED.md).