Docker Local Stack

Overview

Stackpane can launch and manage a local Supabase stack using Docker, giving you a fully functional Supabase environment on your machine. Develop and test against a local PostgreSQL database, GoTrue auth server, Storage API, and more — all without an internet connection or cloud project.

Prerequisites

Before starting the local Supabase stack, ensure the following are installed:

• Docker Desktop — Docker must be installed and running. Stackpane uses Docker Compose to orchestrate the Supabase services.
• Sufficient resources — the full Supabase stack runs multiple containers (PostgreSQL, GoTrue, PostgREST, Storage, Realtime, and others). Allocate at least 4 GB of RAM to Docker.

Stackpane checks for Docker availability before attempting to start the local stack and reports an error if Docker is not running.

Setting Up a Local Connection

1. Click the + button in the sidebar and select New Connection.
2. Enter a connection name (e.g., “Local Development”).
3. Select Supabase as the provider.
4. Choose Local / Docker as the environment type.
5. Configure the local stack settings (or use the defaults).
6. Click Save.

Starting the Local Stack

1. Select your local Supabase connection in the sidebar.
2. Click Start in the emulator panel.
3. Stackpane launches the Docker containers using docker compose.
4. Service health indicators turn green as each service comes online.

The following services are started:

Service	Default Port	Description
PostgreSQL	5432	The core database
PostgREST	3000	REST API for database access
GoTrue	9999	Authentication server
Storage API	5000	File storage service
Realtime	4000	WebSocket server for change subscriptions
Studio	3000	Supabase Studio web UI (optional)

Stopping the Local Stack

Click Stop to shut down all containers. Stackpane sends a graceful shutdown signal via docker compose down. Service indicators turn gray when all containers have stopped.

Data in the PostgreSQL database persists across restarts because it is stored in a Docker volume. To reset the data completely, use the Reset Data option which removes the Docker volumes.

Monitoring

Service Status

The emulator panel shows real-time health status for each service:

• Green — service container is running and healthy
• Yellow — service is starting up
• Gray — service is stopped

Status is updated through periodic polling of Docker container health checks.

Log Viewer

Click Logs to open the log viewer, which aggregates output from all running containers:

• Logs are color-coded by service for easy identification
• Filter logs by service name to focus on a specific container
• Search within logs to find specific entries
• Logs auto-scroll to the latest entries, with a pause button to stop scrolling

Stackpane uses SupabaseLogParser to parse and format container output into a structured, readable log view.

Status Parser

The SupabaseStatusParser monitors container states and translates Docker health check results into the status indicators displayed in the emulator panel. It detects service restarts and connection issues automatically.

Seeding Data

SQL Seed Files

Place SQL files in your project’s seed directory to automatically populate the local database:

1. Create seed SQL files with INSERT statements or function calls.
2. Configure the seed directory path in the connection settings.
3. Click Run Seeds to execute all seed files against the local PostgreSQL instance.

Importing from Production

Use the data import feature to copy a subset of production data into your local stack for realistic development:

1. Create a production Supabase connection if you do not already have one.
2. Export data from production using the export tools.
3. Import the exported data into your local connection.

Differences from Production

While the local stack mirrors production closely, there are some differences to be aware of:

• Edge Functions — Deno-based functions are not included in the default local stack. Use the Supabase CLI separately for local function development.
• Email delivery — GoTrue uses a local email testing tool (like Inbucket) instead of sending real emails. Check the Inbucket UI for confirmation and password reset emails.
• Rate limits — local development has no rate limiting, which may mask issues that appear in production.
• Extensions — some PostgreSQL extensions available on Supabase cloud may need manual installation in the local Docker environment.

Port Configuration

Customize service ports in the connection editor to avoid conflicts with other local services:

1. Open the connection settings.
2. Edit the port mappings for each service.
3. Save and restart the local stack for changes to take effect.

Tips

• Keep Docker Desktop running while working with the local stack
• Use the log viewer to debug issues during development — PostgREST logs are especially helpful for diagnosing query errors
• Reset Docker volumes when you need a completely fresh database
• Seed your local database with realistic data to catch edge cases during development
• Monitor Docker resource usage if the local stack feels slow — increase allocated RAM if needed