Supabase는 오픈소스 기반의 백엔드 서비스(BaaS) 플랫폼이며, Supabase CLI는 로컬 컴퓨터에서 전체 Supabase 백엔드 스택을 직접 구동하고 관리할 수 있도록 지원하는 명령줄 도구입니다. 웹 및 앱 개발 프로젝트에서 클라우드 데이터베이스에 매번 배포하지 않고 오프라인 상태나 독립된 환경에서 데이터 모델링, 인증, API를 빠르게 검증하려면 로컬 개발 환경을 구성해야 합니다.
로컬 머신에 Supabase 스택을 실행하려면 먼저 서비스 컨테이너들을 띄워 줄 컨테이너 런타임이 필요하며, 프로젝트 내에서 도구를 통일되게 다루기 위해 npm 패키지 매니저를 통해 CLI를 설정해야 합니다. 이 글에서는 로컬 Supabase 스택을 실행하기 위한 컨테이너 사전 요구사항을 확인하고, npm 개발 의존성 설치, 프로젝트 초기화, 스택 실행 및 로컬 Studio 콘솔을 통한 정상 작동 판정 절차를 공식 문서를 기반으로 단계별로 정리합니다.
로컬 Supabase 실행을 위한 컨테이너 런타임 요구사항
Supabase CLI로 로컬 개발 스택을 실행(supabase start)하려면 데이터베이스(PostgreSQL), 인증 서비스(GoTrue), API 게이트웨이 등의 컨테이너 서비스들이 함께 구동되어야 합니다. 따라서 시스템에 Docker API와 호환되는 컨테이너 매니저가 사전에 반드시 설치되어 실행 중이어야 합니다.
운영체제별로 권장되는 공식 지원 컨테이너 매니저는 다음과 같습니다.
- macOS: OrbStack(macOS 환경에서 공식 권장) 또는 Docker Desktop, Rancher Desktop, Podman
- Windows: Docker Desktop(공식 권장) 또는 Rancher Desktop, Podman
- Linux: Docker Desktop(공식 권장) 또는 Rancher Desktop, Podman
또한, npm 또는 npx 패키지 러너를 통해 Supabase CLI를 프로젝트 내에서 실행하는 경우 시스템에 Node.js 20 이상의 런타임이 준비되어 있어야 합니다. 컨테이너 런타임 엔진이 백그라운드에서 정상적으로 구동되고 있는지 먼저 확인한 후 CLI 설치 단계로 넘어가야 합니다.
npm 기반 프로젝트에 Supabase CLI 설치하기
Supabase CLI는 Homebrew 등을 통한 전역 도구로 설치할 수도 있지만, 프론트엔드나 백엔드 프로젝트 저장소 단위로 개발 환경을 일치시키기 위해 npm의 개발 의존성(dev dependency)으로 설치하는 방식이 권장됩니다. 프로젝트 내에 설치하면 팀원 전원이 package.json에 명시된 동일한 CLI 버전을 사용할 수 있습니다.
프로젝트 루트 경로의 터미널에서 다음 명령어를 실행하여 Supabase CLI를 추가합니다.
npm install supabase --save-dev설치가 완료되면 패키지 실행 도구인 npx를 사용하여 정상적으로 CLI 명령이 등록되었는지 확인합니다.
npx supabase --help- 터미널을 열고 애플리케이션 코드가 위치한 프로젝트 디렉터리로 이동합니다.
npm install supabase --save-dev명령을 입력하여 의존성 패키지를 설치합니다. (pnpm 사용 시pnpm add -D supabase, yarn 사용 시yarn add -D supabase적용 가능)- 설치가 끝나면
npx supabase --help를 실행하여 사용 가능한 하위 명령어 목록이 출력되는지 확인합니다.
도움말 텍스트 대신 패키지를 찾을 수 없다는 오류가 발생한다면, 명령을 실행한 위치에 package.json 파일이 존재하는지, 그리고 node_modules 디렉터리에 설치가 정상적으로 완료되었는지 점검해야 합니다.
로컬 프로젝트 초기화와 Supabase 스택 실행 흐름
CLI 설치가 완료되었다면 프로젝트 저장소에 로컬 Supabase 설정 파일을 구성하고 전체 백엔드 컨테이너 스택을 기동합니다. 대부분의 CLI 실행 명령은 초기화 작업이 선행된 디렉터리 내에서 동작하도록 설계되어 있습니다.
npx supabase init이 명령을 실행하면 프로젝트 루트에 supabase 디렉터리가 생성되고, 그 내부에 config.toml 파일이 만들어집니다. config.toml은 로컬에서 구동되는 서비스의 핵심 구성을 담고 있으며 주요 설정 영역은 다음과 같습니다.
- project_id: 동일 호스트 내에서 서로 다른 Supabase 프로젝트를 구분하는 문자열로, 기본값은 작업 디렉터리 이름으로 지정됩니다.
- auth: 로컬 인증 서비스 활성화 여부(
auth.enabled), 사이트 기본 URL(auth.site_url, 기본값 “http://localhost:3000”), 리다이렉트 URL 허용 목록, 토큰 만료 시간(auth.jwt_expiry) 등을 설정합니다. - api: 로컬 API 서비스 포트(기본 포트 54321) 및 한 번에 반환되는 최대 행 수(
api.max_rows)를 조정합니다. - db: 로컬 PostgreSQL 데이터베이스 포트(기본 포트 54322) 및 메이저 버전(
db.major_version)을 지정합니다.
설정 파일 생성을 확인한 후 로컬 Supabase 스택을 실행합니다.
npx supabase start- 프로젝트 루트 디렉터리에서
npx supabase init을 입력해 설정 뼈대를 생성합니다. - 컨테이너 매니저(Docker Desktop, OrbStack 등)가 켜져 있는지 확인한 상태에서
npx supabase start를 실행합니다. - 첫 실행 시 필요한 컨테이너 이미지들을 다운로드하는 과정이 진행되며, 완료 후 스택 서비스들이 시작됩니다.
- 작업을 종료하거나 설정을 변경하여 재시작할 때는
npx supabase stop명령으로 로컬 컨테이너들을 안전하게 정지시킵니다.
만약 supabase start 실행 시 데몬에 연결할 수 없다는 에러 메시지가 표시된다면 사전에 실행해 둔 컨테이너 엔진이 꺼져 있거나 Docker 소켓 접근 권한이 없는 상태이므로 컨테이너 매니저의 실행 상태를 우선 확인해야 합니다.
로컬 스택 구동 판정 기준과 Studio 웹 콘솔 접속
npx supabase start 명령이 정상적으로 완료되면 터미널 화면에 각 로컬 서비스의 주소와 접근 키 정보가 담긴 안내 블록이 출력됩니다.
Started supabase local development setup.
╭──────────────────────────────────────╮
│ 🔧 Development Tools │
├─────────┬────────────────────────────┤
│ Studio │ http://127.0.0.1:54323 │
│ Mailpit │ http://127.0.0.1:54324 │
│ MCP │ http://127.0.0.1:54321/mcp │
╰─────────┴────────────────────────────╯
╭──────────────────────────────────────────────────────╮
│ 🌐 APIs │
├────────────────┬─────────────────────────────────────┤
│ Project URL │ http://127.0.0.1:54321 │
│ REST │ http://127.0.0.1:54321/rest/v1 │
│ GraphQL │ http://127.0.0.1:54321/graphql/v1 │
│ Edge Functions │ http://127.0.0.1:54321/functions/v1 │
╰────────────────┴─────────────────────────────────────╯
╭───────────────────────────────────────────────────────────────╮
│ ⛁ Database │
├─────┬─────────────────────────────────────────────────────────┤
│ URL │ postgresql://postgres:postgres@127.0.0.1:54322/postgres │
╰─────┴─────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────╮
│ 🔑 Authentication Keys │
├─────────────┬────────────────────────────────────────────────┤
│ Publishable │ sb_publishable_... │
│ Secret │ sb_secret_... │
╰─────────────┴────────────────────────────────────────────────╯로컬 스택이 올바르게 준비되었는지 최종 판정하는 기준은 웹 브라우저를 통한 Supabase Studio 접속입니다. 브라우저 주소창에 기본 관리 웹 콘솔 주소인 http://localhost:54323 (또는 http://127.0.0.1:54323)을 입력하여 대시보드 화면이 렌더링되는지 확인합니다. Studio 콘솔에서는 로컬 데이터베이스의 테이블 뷰어, SQL 편집기, 인증 사용자 목록 등을 직접 시각적으로 다룰 수 있습니다.
또한 로컬 개발 머신이 신뢰할 수 없는 공용 네트워크나 외부 Wi-Fi에 연결되어 있는 경우, 로컬 서비스가 외부로 노출되지 않도록 호스트 바인딩을 제한해야 합니다. 이러한 보안 격리가 필요하다면 127.0.0.1에 바인딩된 격리 Docker 네트워크를 생성한 후 네트워크 ID를 지정하여 실행하는 공식 방식을 사용합니다.
docker network create -o 'com.docker.network.bridge.host_binding_ipv4=127.0.0.1' local-network
npx supabase start --network-id local-network이와 같이 컨테이너 매니저 실행, npm 기반 CLI 설치, init 및 start 절차를 준수하면 네트워크 연결이 없는 오프라인 환경에서도 안전하고 독립적인 로컬 Supabase 개발 환경을 구축할 수 있습니다.
