usda-vision/docs/RUNNING_SUPABASE_SERVICES.md

# Running Supabase Services with Docker Compose

## Quick Start

### Start All Supabase Services

```bash
# 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-`):

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

### Start All Services (Including Supabase)

```bash
# Start everything including Supabase
docker compose up -d
```

## Individual Service Management

### Start Specific Services

```bash
# 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

```bash
# Stop all Supabase services
docker compose stop supabase-*

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

### Restart Supabase Services

```bash
# Restart all Supabase services
docker compose restart supabase-*

# Restart specific service
docker compose restart supabase-db
```

## Checking Service Status

### List All Supabase Services

```bash
# 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

```bash
# 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

```bash
# 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

```bash
docker compose up -d
```

### Start Only Supabase

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

### Stop Everything

```bash
docker compose down
```

### Stop Only Supabase (Keep Other Services Running)

```bash
docker compose stop supabase-*
```

### View Real-time Logs

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

# Specific service
docker compose logs -f supabase-db
```

### Reset Supabase (Remove Volumes)

```bash
# 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):
   ```bash
   docker login
   ```
3. **Use cached images** if available:
   ```bash
   docker images | grep supabase
   ```

### Services Not Starting

1. **Check logs**:
   ```bash
   docker compose logs supabase-db
   ```

2. **Check if ports are in use**:
   ```bash
   # Check if port 54322 (database) is in use
   sudo lsof -i :54322
   ```

3. **Verify network exists**:
   ```bash
   docker network ls | grep usda-vision
   ```

### Migration Issues

If migrations fail:

1. **Check migration logs**:
   ```bash
   docker compose logs supabase-migrate
   ```

2. **Manually run migrations**:
   ```bash
   docker compose exec supabase-db psql -U postgres -d postgres -f /path/to/migration.sql
   ```

3. **Reset database** (⚠️ **WARNING**: This deletes all data):
   ```bash
   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

```bash
# 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:

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