usda-vision/docs/RUNNING_SUPABASE_SERVICES.md

Running Supabase Services with Docker Compose

Quick Start

Start All Supabase Services

# From project root
docker compose up -d supabase-db supabase-rest supabase-auth supabase-realtime supabase-storage supabase-studio supabase-meta supabase-migrate supabase-inbucket

Or use the shorthand (all services starting with supabase-):

docker compose up -d $(docker compose config --services | grep supabase | tr '\n' ' ')

Start All Services (Including Supabase)

# Start everything including Supabase
docker compose up -d

Individual Service Management

Start Specific Services

# Start just the database
docker compose up -d supabase-db

# Start database + API
docker compose up -d supabase-db supabase-rest

# Start all core services (db, rest, auth)
docker compose up -d supabase-db supabase-rest supabase-auth

Stop Supabase Services

# Stop all Supabase services
docker compose stop supabase-*

# Or stop specific services
docker compose stop supabase-db supabase-rest

Restart Supabase Services

# Restart all Supabase services
docker compose restart supabase-*

# Restart specific service
docker compose restart supabase-db

Checking Service Status

List All Supabase Services

# Using labels (recommended)
docker compose ps --filter "label=com.usda-vision.service=supabase"

# Using service name pattern
docker compose ps supabase-*

# Or just check all services
docker compose ps

View Logs

# All Supabase services
docker compose logs -f supabase-*

# Specific service
docker compose logs -f supabase-db

# Last 50 lines of a service
docker compose logs --tail=50 supabase-migrate

Check Service Health

# Check if database is healthy
docker compose ps supabase-db

# Check migration status
docker compose logs supabase-migrate | tail -20

# Check all Supabase services status
docker compose ps --filter "label=com.usda-vision.service=supabase" --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}"

Service Dependencies

Supabase services have dependencies. Start them in this order for best results:

1. supabase-db - Database (must start first)
2. supabase-migrate - Runs migrations (depends on db)
3. supabase-rest - API (depends on db + migrate)
4. supabase-auth - Authentication (depends on db)
5. supabase-meta - Metadata service (depends on db)
6. supabase-realtime - Realtime (depends on db + rest)
7. supabase-storage - Storage (depends on db + rest)
8. supabase-studio - Studio UI (depends on rest + auth)
9. supabase-inbucket - Email testing (independent)

Note: Docker Compose handles dependencies automatically via depends_on, so you can start them all at once and they'll start in the correct order.

Common Commands

Start Everything

docker compose up -d

Start Only Supabase

docker compose up -d supabase-db supabase-rest supabase-auth supabase-realtime supabase-storage supabase-studio supabase-meta supabase-migrate supabase-inbucket

Stop Everything

docker compose down

Stop Only Supabase (Keep Other Services Running)

docker compose stop supabase-*

View Real-time Logs

# All Supabase services
docker compose logs -f supabase-*

# Specific service
docker compose logs -f supabase-db

Reset Supabase (Remove Volumes)

# Stop and remove Supabase containers and volumes
docker compose down -v supabase-*

# Or use the reset script
./scripts/docker-compose-reset.sh

Troubleshooting

Rate Limit Errors

If you see toomanyrequests: Rate exceeded, Docker Hub is rate-limiting you. Solutions:

1. Wait a few minutes and try again
2. Login to Docker Hub (increases rate limit):

   docker login
   

3. Use cached images if available:

   docker images | grep supabase
   

Services Not Starting

1. Check logs:

   docker compose logs supabase-db
   

2. Check if ports are in use:

   # Check if port 54322 (database) is in use
   sudo lsof -i :54322
   

3. Verify network exists:

   docker network ls | grep usda-vision
   

Migration Issues

If migrations fail:

1. Check migration logs:

   docker compose logs supabase-migrate
   

2. Manually run migrations:

   docker compose exec supabase-db psql -U postgres -d postgres -f /path/to/migration.sql
   

3. Reset database (⚠️ WARNING: This deletes all data):

   docker compose down -v supabase-db
   docker compose up -d supabase-db
   

Service URLs

Once running, access services at:

• Supabase API: http://localhost:54321
• Supabase Studio: http://localhost:54323
• Database (direct): postgresql://postgres:postgres@localhost:54322/postgres
• Email Testing (Inbucket): http://localhost:54324
• Realtime: ws://localhost:4000
• Storage API: http://localhost:5000

Best Practices

1. Always start database first (or let Compose handle dependencies)
2. Wait for migrations before starting dependent services
3. Check logs if services fail to start
4. Use labels to filter and manage Supabase services
5. Keep volumes for persistent data (don't use -v flag unless resetting)

Example: Full Startup Sequence

# 1. Start database
docker compose up -d supabase-db

# 2. Wait for database to be ready (check logs)
docker compose logs -f supabase-db

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

# 4. Verify all services are running
docker compose ps --filter "label=com.usda-vision.service=supabase"

Or simply:

# Start everything at once (Compose handles dependencies)
docker compose up -d