Supabase 도커(Docker)로 로컬 개발 환경 구축하기

Supabase 도커(Docker)로 로컬 개발 환경 구축하기

1. Supabase란?

Supabase는 오픈소스 기반의 BaaS(Backend as a Service) 플랫폼입니다. 구글의 Firebase와 유사한 경험을 제공하지만, 가장 큰 차이점은 PostgreSQL(SQL)을 기반으로 한다는 점입니다.

• 주요 기능: 인증(Auth), 실시간 데이터베이스, 스토리지, Edge Functions 등.
• 장점: SQL의 강력한 쿼리 기능을 그대로 사용하면서, 백엔드 구축 없이 API를 자동으로 생성해 줍니다. 개발 속도를 극대화하고 프론트엔드 로직에만 집중할 수 있게 돕습니다.

2. 왜 Docker로 로컬 환경을 구축해야 할까?

클라우드 버전을 사용할 수도 있지만, 도커를 통한 Self-hosting은 다음과 같은 이점이 있습니다.

1. 비용 절감: 프로젝트 개수나 데이터 제한 없이 무료로 사용 가능합니다.
2. 독립적 환경: 오프라인 상태에서도 개발이 가능하며, 보안상 로컬 네트워크 내에서만 데이터를 관리할 때 유리합니다.

도커를 통한 self hosting은 아래의 공식문서를 참고

https://supabase.com/docs/guides/self-hosting/docker

3. Supabase 도커 설치 단계

Step 1. 저장소 클론 (Clone Repository)

내부에 docker-compose.yml 파일이 존재한다.

# 코드 가져오기
$ git clone https://github.com/supabase/supabase 

# 설정 파일이 있는 위치로 이동
$ cd supabase/docker

# 기본 .env 파일 복사
cp .env.example .env

Step 2. .env 파일 핵심 설정 (필수 수정)

실행 전 보안과 정상 작동을 위해 .env 파일에서 아래 항목들을 반드시 수정해야 합니다.

• POSTGRES_PASSWORD: PostgreSQL 접속 비밀번호
• JWT_SECRET: Supabase Auth와 RLS에 사용하는 JWT 서명 키
• ANON_KEY: 클아이언트가 사용할 수 있는 공개 키
• SERVICE_ROLE_KEY: 서버 측에서만 사용할 수 있는 권한 높은 JWT
• DASHBOARD_USERNAME: Supabase Studio 로그인 ID
• DASHBOARD_PASSWORD: Supabase Studio 로그인 비밀번호
• SECRET_KEY_BASE: Supabase 내부에서 사용하는 Rails 비밀키
• VAULT_ENC_KEY: 환경 변수 암호화를 위한 Valut 암호화 키(32자 이상)

💡 보안 팁: 로컬 테스트용이더라도 비밀번호와 키값은 가급적 복잡하게 설정하는 것이 좋습니다.

예제 .env

# 1. Postgres Database Settings
POSTGRES_DB=postgres
POSTGRES_PASSWORD=your_strong_password_here  # 여기에 원하는 비밀번호 입력
POSTGRES_PORT=5432
POSTGRES_HOST=db  # 도커 네트워크 안에서 실행될 경우 'db'

# 2. Auth (JWT) Settings
# https://pwc-demo.supabase.co/ 에서 생성하거나 무작위 32자 이상 문자열
JWT_SECRET=your_jwt_secret_must_be_at_least_32_characters_long
SECRET_KEY_BASE=your_random_secret_key_base
VAULT_ENC_KEY=your_vault_encryption_key

# 3. Connection Pooler Settings
POOLER_TENANT_ID=supabase_local
POOLER_DEFAULT_POOL_SIZE=10
POOLER_MAX_CLIENT_CONN=100
POOLER_DB_POOL_SIZE=10

# 4. API & Port Settings (보여주신 설정 기준)
PORT=4000
REGION=local

# 5. Dashboard & Edge Functions (추가로 필요한 경우)
SITE_URL=http://localhost:3000
API_EXTERNAL_URL=http://localhost:8000

Step 3. 컨테이너 실행

$ docker-compose up -d

Step 4. 접속 테스트 및 환경 확인

http://localhost:3000  (Supabase Studio 접속)
http://localhost:5432  (PostgreSQL 접속, ID: postgres, PW: postgres)
http://localhost:8000/rest/v1  (자동 생성된 API)