# Supabase Self-Hosted

> Self-hosted Supabase with PostgreSQL, GoTrue auth, PostgREST, and Realtime.

- Category: Full Web Stacks
- Difficulty: advanced
- Components: postgres, postgrest, gotrue, realtime, storage, kong
- Tags: supabase, postgres, realtime, auth, backend-as-service
- Source: https://docker.recipes/full-stacks/supabase-stack

## Overview

Supabase is an open-source Firebase alternative that combines PostgreSQL with a comprehensive backend-as-a-service platform, providing real-time subscriptions, authentication, instant APIs, and file storage. This self-hosted stack integrates PostgreSQL as the core database with PostgREST for automatic API generation, GoTrue for authentication management, Realtime for WebSocket connections, and Kong Gateway for API routing and security. The platform transforms a traditional PostgreSQL database into a modern, API-first backend with real-time capabilities, eliminating the need to build authentication systems, API endpoints, and WebSocket infrastructure from scratch. This configuration is ideal for developers who want the full power of Supabase without vendor lock-in, organizations requiring data sovereignty, and teams building applications that need PostgreSQL's advanced features alongside modern backend services. The stack provides enterprise-grade authentication flows, automatic REST and GraphQL APIs from database schemas, real-time database change subscriptions, and secure file storage with access controls.

## Features

- Automatic REST API generation from PostgreSQL schemas using PostgREST with row-level security
- Real-time database change subscriptions via WebSockets for live application updates
- Complete authentication system with GoTrue supporting email, OAuth, and magic link flows
- File storage API with access control policies and automatic image transformations
- Kong Gateway providing rate limiting, CORS handling, and API authentication middleware
- PostgreSQL Row Level Security (RLS) integration for fine-grained data access control
- Supabase Studio web interface for database management and API testing
- JWT-based authentication with configurable token expiration and refresh flows

## Use cases

- Building real-time collaborative applications like chat systems or document editors
- Creating SaaS platforms requiring multi-tenant data isolation with PostgreSQL RLS
- Developing mobile applications needing offline sync and real-time data synchronization
- Prototyping full-stack applications without building custom backend infrastructure
- Migrating from Firebase to maintain data sovereignty while keeping similar functionality
- Building internal tools requiring rapid API development from existing PostgreSQL schemas
- Creating content management systems with user authentication and file upload capabilities

## Prerequisites

- Docker and Docker Compose with at least 4GB RAM available for all services
- Supabase CLI installed for generating JWT secrets and API keys
- Basic understanding of PostgreSQL Row Level Security and database schema design
- Kong configuration knowledge for customizing API gateway routing rules
- Ports 3000, 8000, and 8443 available on the host system
- Understanding of JWT authentication flows and token management

## docker-compose.yml

```yaml
services:
  kong:
    image: kong:2.8
    container_name: supabase-kong
    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
    ports:
      - "8000:8000"
      - "8443:8443"
    networks:
      - supabase-network

  db:
    image: supabase/postgres:15.1.0.117
    container_name: supabase-db
    environment:
      - POSTGRES_HOST=/var/run/postgresql
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
    networks:
      - supabase-network

  auth:
    image: supabase/gotrue:v2.132.3
    container_name: supabase-auth
    environment:
      - GOTRUE_API_HOST=0.0.0.0
      - GOTRUE_API_PORT=9999
      - API_EXTERNAL_URL=${API_EXTERNAL_URL}
      - GOTRUE_DB_DRIVER=postgres
      - GOTRUE_DB_DATABASE_URL=postgres://supabase_auth_admin:${POSTGRES_PASSWORD}@db:5432/postgres
      - GOTRUE_SITE_URL=${SITE_URL}
      - GOTRUE_JWT_SECRET=${JWT_SECRET}
      - GOTRUE_JWT_EXP=3600
    depends_on:
      db:
        condition: service_healthy
    networks:
      - supabase-network

  rest:
    image: postgrest/postgrest:v11.2.2
    container_name: supabase-rest
    environment:
      - PGRST_DB_URI=postgres://authenticator:${POSTGRES_PASSWORD}@db:5432/postgres
      - PGRST_DB_SCHEMAS=public,storage
      - PGRST_DB_ANON_ROLE=anon
      - PGRST_JWT_SECRET=${JWT_SECRET}
    depends_on:
      db:
        condition: service_healthy
    networks:
      - supabase-network

  realtime:
    image: supabase/realtime:v2.25.35
    container_name: supabase-realtime
    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'
      - API_JWT_SECRET=${JWT_SECRET}
      - SECRET_KEY_BASE=${SECRET_KEY_BASE}
    depends_on:
      db:
        condition: service_healthy
    networks:
      - supabase-network

  storage:
    image: supabase/storage-api:v0.43.11
    container_name: supabase-storage
    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
      - FILE_SIZE_LIMIT=52428800
      - STORAGE_BACKEND=file
      - FILE_STORAGE_BACKEND_PATH=/var/lib/storage
    volumes:
      - storage_data:/var/lib/storage
    depends_on:
      db:
        condition: service_healthy
    networks:
      - supabase-network

  studio:
    image: supabase/studio:20231123-64a766a
    container_name: supabase-studio
    environment:
      - STUDIO_PG_META_URL=http://meta:8080
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - SUPABASE_URL=http://kong:8000
      - SUPABASE_PUBLIC_URL=${API_EXTERNAL_URL}
      - SUPABASE_ANON_KEY=${ANON_KEY}
      - SUPABASE_SERVICE_KEY=${SERVICE_ROLE_KEY}
    ports:
      - "3000:3000"
    depends_on:
      - kong
    networks:
      - supabase-network

  meta:
    image: supabase/postgres-meta:v0.68.0
    container_name: supabase-meta
    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:
        condition: service_healthy
    networks:
      - supabase-network

volumes:
  postgres_data:
  storage_data:

networks:
  supabase-network:
    driver: bridge
```

## .env

```bash
# Supabase Self-Hosted
POSTGRES_PASSWORD=your-super-secret-password
JWT_SECRET=your-super-secret-jwt-token-with-at-least-32-characters
ANON_KEY=your-anon-key
SERVICE_ROLE_KEY=your-service-role-key
SECRET_KEY_BASE=your-secret-key-base
API_EXTERNAL_URL=http://localhost:8000
SITE_URL=http://localhost:3000
```

## Usage notes

- Studio UI at http://localhost:3000
- API Gateway at http://localhost:8000
- Generate keys using Supabase CLI
- Create volumes/kong/kong.yml config
- See Supabase docs for full setup

## Troubleshooting

- GoTrue auth service fails to start: Ensure JWT_SECRET is exactly 32 characters and matches across all services
- PostgREST returns 401 errors: Verify the authenticator role exists in PostgreSQL and has correct permissions
- Realtime subscriptions not working: Check that the _realtime schema is properly initialized in PostgreSQL
- Kong gateway returns 502 errors: Ensure kong.yml configuration file exists and contains proper service definitions
- Storage API upload failures: Verify FILE_SIZE_LIMIT environment variable and storage bucket policies are configured
- Studio interface shows connection errors: Check that SUPABASE_URL points to Kong gateway and all API keys are valid

