usda-vision/docs/SUPABASE_DOCKER_COMPOSE.md

Supabase Integration with Docker Compose

The Supabase containers are now integrated into the main docker-compose.yml file, so you no longer need to start them separately from the management-dashboard-web-app directory.

What Changed

All Supabase services are now defined in the root docker-compose.yml:

• supabase-db: PostgreSQL database (port 54322)
• supabase-rest: PostgREST API (port 54321)
• supabase-auth: GoTrue authentication service (port 9999)
• supabase-realtime: Realtime subscriptions (port 4000)
• supabase-storage: Storage API (port 5000)
• supabase-studio: Supabase Studio UI (port 54323)
• supabase-meta: Database metadata service (port 54328)
• supabase-inbucket: Email testing server (port 54324)
• supabase-migrate: Migration runner (runs once on startup)

Usage

Starting All Services

Simply run from the project root:

docker compose up -d

This will start all services including Supabase containers.

Environment Variables

The Supabase services use the following environment variables (with defaults for local development):

• POSTGRES_PASSWORD: Database password (default: your-super-secret-and-long-postgres-password)
• JWT_SECRET: JWT signing secret (default: your-super-secret-jwt-token-with-at-least-32-characters-long)
• ANON_KEY: Anonymous/public key for client-side access
• SERVICE_KEY: Service role key for server-side access

You can set these in a .env file in the project root, or export them before running docker compose up.

Web App Configuration

Make sure your management-dashboard-web-app/.env file has:

VITE_SUPABASE_URL=http://localhost:54321
VITE_SUPABASE_ANON_KEY=<your-anon-key>

The default anon key for local development is:

[REDACTED]

Migrations

Migrations are automatically run on first startup via the supabase-migrate service. The service:

1. Waits for the database to be ready
2. Runs all migrations from management-dashboard-web-app/supabase/migrations/ in alphabetical order
3. Runs seed files (seed_01_users.sql and seed_02_phase2_experiments.sql)

If you need to re-run migrations, you can:

1. Stop the containers: docker compose down
2. Remove the database volume: docker volume rm usda-vision_supabase-db
3. Start again: docker compose up -d

Accessing Services

• Supabase API: http://localhost:54321
• Supabase Studio: http://localhost:54323
• Email Testing (Inbucket): http://localhost:54324
• Database (direct): localhost:54322

Network

All services are on the usda-vision-network bridge network, so they can communicate with each other using service names (e.g., supabase-db, supabase-rest).

Migration from Supabase CLI

If you were previously using supabase start from the management-dashboard-web-app directory:

1. Stop any running Supabase containers from the CLI
2. The new setup uses the same ports, so make sure nothing is conflicting
3. Start the new setup with docker compose up -d from the project root

Troubleshooting

Port Conflicts

If you get port conflicts, make sure:

• No other Supabase instances are running
• The Supabase CLI isn't running containers (supabase stop if needed)

Migration Issues

If migrations fail:

1. Check the logs: docker compose logs supabase-migrate
2. Ensure migration files are valid SQL
3. You may need to manually connect to the database and fix issues

Database Connection Issues

If services can't connect to the database:

1. Check database is healthy: docker compose ps supabase-db
2. Check logs: docker compose logs supabase-db
3. Ensure the database password matches across all services