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

   pip install huggingface-hub
   huggingface-cli login
   

Step 1: Test Locally

Before deploying, ensure everything works locally:

# 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)

./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

# 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

# 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

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:

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:

git add images/
git commit -m "Add sample images"
git push hf main

Changes Not Showing

Force update:

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:

# 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 or GETTING_STARTED.md.