DEPLOYMENT_GUIDE.md

🚀 Deployment Guide for Hugging Face Spaces

This guide will walk you through deploying the Turnstile Solver API to Hugging Face Spaces.

Prerequisites

• A Hugging Face account (free): https://huggingface.co/join
• Git installed on your computer (optional, can use web interface)

Method 1: Web Interface (Easiest)

Step 1: Create a New Space

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Fill in the details:
   • Space name: turnstile-solver (or any name you prefer)
   • License: MIT
   • Select the Space SDK: Choose Docker
   • Space hardware: CPU basic (free tier)
   • Visibility: Public or Private (your choice)
4. Click "Create Space"

Step 2: Upload Files

1. Once your Space is created, you'll see an empty repository
2. Click "Files" tab
3. Click "Add file" → "Upload files"
4. Upload these files from the turnstile-solver-hf folder:
   • app.py
   • requirements.txt
   • Dockerfile
   • README.md
   • .dockerignore
5. Click "Commit changes to main"

Step 3: Wait for Build

1. The Space will automatically start building the Docker container
2. This takes about 5-10 minutes
3. You can watch the build logs in the "Logs" tab
4. Once complete, your API will be live!

Step 4: Test Your API

Your API will be available at:

https://huggingface.co/spaces/YOUR-USERNAME/turnstile-solver

Test it:

curl "https://YOUR-USERNAME-turnstile-solver.hf.space/turnstile?url=https://example.com&sitekey=0x4AAAAAAB6qwG1HcvybuFht"

Method 2: Git CLI (Advanced)

Step 1: Create Space on HF

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Choose Docker SDK
4. Note your Space URL

Step 2: Clone and Push

# Clone your empty Space
git clone https://huggingface.co/spaces/YOUR-USERNAME/turnstile-solver
cd turnstile-solver

# Copy files from turnstile-solver-hf folder
cp ../turnstile-solver-hf/* .

# Add and commit
git add .
git commit -m "Initial deployment"

# Push to HF
git push

Step 3: Monitor Build

Watch the build process at:

https://huggingface.co/spaces/YOUR-USERNAME/turnstile-solver

Configuration Options

Change Port (Optional)

The default port is 7860. To change it, modify Dockerfile:

ENV PORT=8080
EXPOSE 8080

Enable GPU (Optional)

For faster processing, upgrade to GPU hardware:

1. Go to Space Settings
2. Change "Space hardware" to "GPU basic"
3. Note: This requires a paid plan

Add Authentication (Optional)

To protect your API, add basic auth in app.py:

from quart import request
from functools import wraps

def require_auth(f):
    @wraps(f)
    async def decorated(*args, **kwargs):
        auth = request.headers.get('Authorization')
        if auth != 'Bearer YOUR_SECRET_TOKEN':
            return jsonify({"error": "Unauthorized"}), 401
        return await f(*args, **kwargs)
    return decorated

@app.route('/turnstile')
@require_auth
async def process_turnstile():
    # ... existing code

Troubleshooting

Build Fails

Error: "No space left on device"

• Solution: Reduce Docker image size by removing unnecessary dependencies

Error: "Chromium installation failed"

• Solution: Check Dockerfile has all required system dependencies

API Not Responding

Check Logs:

1. Go to your Space
2. Click "Logs" tab
3. Look for errors

Common Issues:

• Port mismatch: Ensure PORT env variable matches EXPOSE in Dockerfile
• Memory limit: Free tier has 16GB RAM limit
• Timeout: Increase timeout in Space settings

Slow Performance

Solutions:

1. Upgrade to GPU hardware
2. Reduce concurrent tasks
3. Optimize browser launch parameters

Monitoring

View Logs

# Real-time logs
https://huggingface.co/spaces/YOUR-USERNAME/turnstile-solver/logs

Health Check

curl https://YOUR-USERNAME-turnstile-solver.hf.space/health

Updating Your Space

Via Web Interface

1. Go to your Space
2. Click "Files"
3. Click on file to edit
4. Make changes
5. Commit

Via Git

cd turnstile-solver
# Make changes to files
git add .
git commit -m "Update description"
git push

Cost Considerations

Free Tier

• CPU basic: Free
• 16GB RAM
• 50GB storage
• No GPU

Paid Tiers

• GPU basic: ~$0.60/hour
• GPU T4: ~$0.90/hour
• More RAM/storage available

Security Best Practices

1. Don't commit secrets: Use HF Secrets for API keys
2. Rate limiting: Implement rate limiting in production
3. Authentication: Add auth for production use
4. Monitoring: Set up alerts for unusual activity
5. Updates: Keep dependencies updated

Support

• HF Spaces Docs: https://huggingface.co/docs/hub/spaces
• Community Forum: https://discuss.huggingface.co/
• Discord: https://discord.gg/hugging-face

Next Steps

1. ✅ Deploy your Space
2. ✅ Test the API
3. ✅ Share your Space URL
4. ✅ Monitor usage
5. ✅ Iterate and improve

Happy deploying! 🚀