usda-vision/docs/DOCKER_RATE_LIMIT_FIX.md

Fixing Docker Hub Rate Limit Issues

Problem

When pulling multiple Docker images, you may encounter:

Error response from daemon: toomanyrequests: Rate exceeded

This happens because Docker Hub limits the number of image pulls for anonymous users.

Solutions

Solution 1: Login to Docker Hub (Recommended)

Logging in to Docker Hub increases your rate limit significantly:

docker login

Enter your Docker Hub username and password. This increases your rate limit from ~100 pulls per 6 hours to ~200 pulls per 6 hours.

Solution 2: Pull Images One at a Time

Use the provided script to pull images with delays:

./scripts/pull-supabase-images.sh

This script:

• Pulls images one at a time
• Waits 10 seconds between pulls
• Retries on rate limit errors
• Shows progress and summary

Solution 3: Manual Pull with Delays

Pull images manually with delays:

# Pull one image at a time with delays
docker compose pull supabase-db
sleep 10
docker compose pull supabase-rest
sleep 10
docker compose pull supabase-auth
sleep 10
# ... continue for other services

Solution 4: Wait and Retry

If you hit the rate limit:

1. Wait 5-10 minutes for the rate limit window to reset
2. Try again:

   docker compose pull supabase-*
   

Solution 5: Use Cached Images

Check if images are already available locally:

# Check what Supabase images you have
docker images | grep supabase

# If images exist, you can start services without pulling
docker compose up -d supabase-*

Current Rate Limits

• Anonymous users: ~100 pulls per 6 hours per IP
• Authenticated users: ~200 pulls per 6 hours per account
• Paid plans: Higher limits

Quick Fix for Supabase Services

If you just need to start Supabase services and have some images cached:

# 1. Check what's already available
docker images | grep -E "(supabase|postgres|inbucket)"

# 2. Try starting services (will only pull missing images)
docker compose up -d supabase-db supabase-rest supabase-auth supabase-realtime supabase-storage supabase-studio supabase-meta supabase-migrate supabase-inbucket

# 3. If rate limited, wait 5 minutes and try pulling specific images:
docker compose pull supabase-rest
# Wait 10 seconds
docker compose pull supabase-auth
# Continue...

Alternative: Use AWS ECR Directly

Since Supabase images are on AWS ECR (public.ecr.aws/supabase/), you can pull directly:

# Pull directly from ECR (may have different rate limits)
docker pull public.ecr.aws/supabase/postgrest:v12.2.12
docker pull public.ecr.aws/supabase/gotrue:v2.177.0
# ... etc

Prevention

1. Always login: docker login before pulling many images
2. Use local images: Keep images locally when possible
3. Pull gradually: Don't pull all images at once
4. Use image caching: Docker caches layers, so subsequent pulls are faster

Verify Images Are Available

After pulling, verify:

# List all Supabase-related images
docker images | grep -E "(supabase|postgrest|gotrue|realtime|storage|studio|postgres-meta|inbucket)"

# Check specific service images
docker images public.ecr.aws/supabase/postgrest
docker images public.ecr.aws/supabase/gotrue

Start Services After Pulling

Once images are pulled:

# Start all Supabase services
docker compose up -d supabase-db supabase-rest supabase-auth supabase-realtime supabase-storage supabase-studio supabase-meta supabase-migrate supabase-inbucket

# Or start everything
docker compose up -d