# Supabase (Self-Hosted)

> Open-source Firebase alternative with Postgres, Auth, Storage, and Realtime subscriptions

- Category: Full Web Stacks
- Difficulty: advanced
- Components: supabase-studio, postgres, kong, gotrue, realtime, storage
- Tags: baas, postgres, auth, storage, realtime, api
- Source: https://docker.recipes/full-stacks/supabase

## Overview

Supabase is an open-source Backend-as-a-Service (BaaS) platform that positions itself as a Firebase alternative, built on top of PostgreSQL with a suite of complementary tools. Originally created by Paul Copplestone and Ant Wilson in 2020, Supabase provides developers with authentication, real-time subscriptions, file storage, and auto-generated APIs without sacrificing the power and flexibility of SQL. Unlike Firebase's NoSQL approach, Supabase leverages PostgreSQL's mature ecosystem while adding modern developer experience features like real-time capabilities and instant APIs.

This self-hosted stack orchestrates seven specialized components to deliver a complete backend platform: Supabase Studio provides the web-based dashboard for database management and API testing, while PostgreSQL serves as the robust foundation with built-in Row Level Security. Kong Gateway acts as the intelligent API proxy, routing requests between GoTrue for authentication, PostgREST for auto-generated REST APIs, Realtime for WebSocket subscriptions, and Storage API for file management. The postgres-meta service enables Studio's database introspection capabilities, creating a unified development experience.

This configuration targets teams seeking Firebase-like developer experience while maintaining full control over their data and infrastructure. Startups can rapidly prototype applications with built-in authentication and real-time features, while enterprises benefit from PostgreSQL's ACID compliance, advanced querying capabilities, and the ability to customize every component. The self-hosted approach eliminates vendor lock-in concerns and allows for compliance with strict data residency requirements that SaaS solutions cannot accommodate.

## Features

- Auto-generated REST and GraphQL APIs from PostgreSQL schema via PostgREST with automatic OpenAPI documentation
- Real-time subscriptions using PostgreSQL's logical replication with WebSocket broadcasting for live data updates
- Row Level Security (RLS) policies directly in PostgreSQL for fine-grained access control without application-level permissions
- Multi-provider authentication through GoTrue supporting email, OAuth providers, and magic links with JWT token management
- File storage with automatic image transformations, resumable uploads, and PostgreSQL metadata integration
- Database management GUI through Studio with visual schema editor, SQL query interface, and API testing playground
- Kong Gateway routing with rate limiting, CORS handling, and request transformation for production API management
- Built-in database functions and triggers support for complex business logic execution at the database layer

## Use cases

- SaaS applications requiring user authentication, file uploads, and real-time collaboration features like document editing or chat
- E-commerce platforms needing inventory management with real-time stock updates and secure payment processing workflows
- Content management systems with multi-user editing, media storage, and role-based access control requirements
- IoT dashboards collecting sensor data with real-time visualization and historical analytics stored in PostgreSQL
- Multi-tenant applications using PostgreSQL schemas or RLS policies for complete data isolation between customers
- Compliance-sensitive applications in healthcare, finance, or government requiring on-premises data storage
- Development teams migrating from Firebase who need SQL capabilities while preserving real-time functionality

## Prerequisites

- Minimum 4GB RAM and 20GB storage for the complete stack with PostgreSQL, Kong, and all Supabase services
- Docker and Docker Compose v2+ with ability to bind to ports 3000, 5432, 8000, and 8001 on the host system
- Generated JWT secret key (32+ characters) and Supabase API keys using supabase CLI or online JWT generator
- Kong declarative configuration file created at ./volumes/kong/kong.yml with service routing definitions
- Basic PostgreSQL knowledge for schema design, RLS policies, and understanding of database user roles
- Familiarity with REST API concepts and JWT authentication for integration with client applications

## docker-compose.yml

```yaml
services:
  studio:
    image: supabase/studio:latest
    container_name: supabase-studio
    restart: unless-stopped
    ports:
      - "${STUDIO_PORT:-3000}:3000"
    environment:
      - STUDIO_PG_META_URL=http://meta:8080
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - DEFAULT_ORGANIZATION_NAME=Default
      - DEFAULT_PROJECT_NAME=Default
      - SUPABASE_URL=http://kong:8000
      - SUPABASE_PUBLIC_URL=http://localhost:${KONG_PORT:-8000}
      - SUPABASE_ANON_KEY=${ANON_KEY}
      - SUPABASE_SERVICE_KEY=${SERVICE_ROLE_KEY}
    depends_on:
      - meta

  kong:
    image: kong:2.8.1
    container_name: supabase-kong
    restart: unless-stopped
    ports:
      - "${KONG_PORT:-8000}:8000"
      - "${KONG_ADMIN_PORT:-8001}:8001"
    environment:
      - KONG_DATABASE=off
      - KONG_DECLARATIVE_CONFIG=/var/lib/kong/kong.yml
      - KONG_DNS_ORDER=LAST,A,CNAME
      - KONG_PLUGINS=request-transformer,cors,key-auth,acl
    volumes:
      - ./volumes/kong/kong.yml:/var/lib/kong/kong.yml:ro

  auth:
    image: supabase/gotrue:latest
    container_name: supabase-auth
    restart: unless-stopped
    environment:
      - GOTRUE_API_HOST=0.0.0.0
      - GOTRUE_API_PORT=9999
      - GOTRUE_DB_DRIVER=postgres
      - GOTRUE_DB_DATABASE_URL=postgres://supabase_auth_admin:${POSTGRES_PASSWORD}@db:5432/postgres
      - GOTRUE_SITE_URL=${SITE_URL:-http://localhost:3000}
      - GOTRUE_JWT_SECRET=${JWT_SECRET}
      - GOTRUE_JWT_EXP=3600
    depends_on:
      - db

  realtime:
    image: supabase/realtime:latest
    container_name: supabase-realtime
    restart: unless-stopped
    environment:
      - PORT=4000
      - DB_HOST=db
      - DB_PORT=5432
      - DB_USER=supabase_admin
      - DB_PASSWORD=${POSTGRES_PASSWORD}
      - DB_NAME=postgres
      - DB_AFTER_CONNECT_QUERY=SET search_path TO _realtime
      - DB_ENC_KEY=supabasekey
      - API_JWT_SECRET=${JWT_SECRET}
      - SECRET_KEY_BASE=${SECRET_KEY_BASE}
    depends_on:
      - db

  storage:
    image: supabase/storage-api:latest
    container_name: supabase-storage
    restart: unless-stopped
    environment:
      - ANON_KEY=${ANON_KEY}
      - SERVICE_KEY=${SERVICE_ROLE_KEY}
      - POSTGREST_URL=http://rest:3000
      - PGRST_JWT_SECRET=${JWT_SECRET}
      - DATABASE_URL=postgres://supabase_storage_admin:${POSTGRES_PASSWORD}@db:5432/postgres
      - STORAGE_BACKEND=file
      - FILE_STORAGE_BACKEND_PATH=/var/lib/storage
      - TENANT_ID=stub
      - REGION=stub
      - GLOBAL_S3_BUCKET=stub
    volumes:
      - ./volumes/storage:/var/lib/storage
    depends_on:
      - db
      - rest

  rest:
    image: postgrest/postgrest:latest
    container_name: supabase-rest
    restart: unless-stopped
    environment:
      - PGRST_DB_URI=postgres://authenticator:${POSTGRES_PASSWORD}@db:5432/postgres
      - PGRST_DB_SCHEMAS=public,storage,graphql_public
      - PGRST_DB_ANON_ROLE=anon
      - PGRST_JWT_SECRET=${JWT_SECRET}
    depends_on:
      - db

  meta:
    image: supabase/postgres-meta:latest
    container_name: supabase-meta
    restart: unless-stopped
    environment:
      - PG_META_PORT=8080
      - PG_META_DB_HOST=db
      - PG_META_DB_PORT=5432
      - PG_META_DB_NAME=postgres
      - PG_META_DB_USER=supabase_admin
      - PG_META_DB_PASSWORD=${POSTGRES_PASSWORD}
    depends_on:
      - db

  db:
    image: supabase/postgres:15.1.0.117
    container_name: supabase-db
    restart: unless-stopped
    ports:
      - "${DB_PORT:-5432}:5432"
    environment:
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_HOST=/var/run/postgresql
    volumes:
      - ./volumes/db/data:/var/lib/postgresql/data
    healthcheck:
      test: pg_isready -U postgres -h localhost
      interval: 5s
      timeout: 5s
      retries: 10
```

## .env

```bash
# Supabase Configuration
STUDIO_PORT=3000
KONG_PORT=8000
DB_PORT=5432

# Database password
POSTGRES_PASSWORD=your-super-secret-password

# JWT Secret (generate with: openssl rand -base64 32)
JWT_SECRET=your-jwt-secret-at-least-32-characters

# Secret key base for Realtime
SECRET_KEY_BASE=your-secret-key-base-at-least-64-characters

# API Keys (generate these or use Supabase CLI)
ANON_KEY=your-anon-key
SERVICE_ROLE_KEY=your-service-role-key

# Site URL
SITE_URL=http://localhost:3000
```

## Usage notes

- Studio dashboard at http://localhost:3000
- API endpoint at http://localhost:8000
- Direct Postgres access at localhost:5432
- Generate JWT keys using Supabase CLI or online generator
- Create Kong config at ./volumes/kong/kong.yml
- See github.com/supabase/supabase/docker for full setup

## Troubleshooting

- Studio shows 'Failed to connect to Postgres' error: Verify POSTGRES_PASSWORD matches between studio and db services, check that postgres-meta container is running and accessible
- Kong returns 503 Service Unavailable: Ensure kong.yml configuration file exists and contains valid service definitions for auth, rest, realtime, and storage endpoints
- GoTrue authentication fails with invalid JWT: Regenerate JWT_SECRET ensuring it matches across auth, rest, realtime, and storage services, restart all dependent containers
- Real-time subscriptions not working: Check that _realtime schema exists in PostgreSQL and DB_ENC_KEY is set correctly in realtime service environment
- Storage API file uploads return 400 errors: Verify storage volume permissions and ensure postgrest service is accessible from storage container
- Studio dashboard loads but shows empty database: Confirm supabase_admin user has proper permissions and postgres-meta can connect with correct credentials

