Supabase 로컬 개발 환경 구축 시 발생하는 문제 완벽 해결법
요즘 Supabase를 활용한 프로젝트를 진행하는 분들이 많아지고 있습니다.
저도 최근 프로젝트에서 Supabase를 도입했는데, 로컬 개발 환경을 구축하는 과정이 의외로 까다로웠습니다.
특히 supabase start 명령어가 제대로 작동하지 않아 개발을 시작하는 데 어려움을 겪었는데요.
이번 글에서는 제가 겪은 문제와 이를 해결한 방법을 공유해 드리려 합니다.
Supabase Local Development란?
본격적인 문제 해결에 앞서, Supabase의 로컬 개발 환경이 왜 중요한지 간단히 이야기해볼게요. Supabase는 Firebase의 오픈소스 대안으로, 데이터베이스, 인증, 스토리지 등 다양한 백엔드 서비스를 제공합니다.
로컬 개발 환경을 구축하면 다음과 같은 이점이 있습니다:
- 클라우드 리소스 사용 없이 로컬에서 모든 기능 테스트 가능
- 비용 발생 없이 무제한 개발 작업 가능
- 인터넷 연결 없이도 작업 가능
- 실수로 프로덕션 데이터를 손상시킬 위험 없음
그런데 이러한 로컬 환경 구축에서 Docker 관련 설정이 문제가 되곤 합니다.
발생한 문제들
Supabase 로컬 개발 환경을 구축하려고 supabase start 명령어를 실행했을 때 다음과 같은 오류 메시지가 나타났습니다:
1PS C:\dev\d-sket-project\d-sket-client-dashboard> supabase start
2supabase : 'supabase' 용어가 cmdlet, 함수, 스크립트 파일 또는 실행할 수 있는 프로그램 이름으로 인식되지 않습니다.그래서 NPX를 통해 실행해봤지만, 이번에는 또 다른 오류가 발생했습니다:
1PS C:\dev\d-sket-project\d-sket-client-dashboard> npx supabase start
2WARNING: analytics requires docker daemon exposed on tcp://localhost:2375
3Stopping containers...
4failed to create docker container: Error response from daemon: Conflict. The container name "/supabase_vector_d-sket-client-dashboard" is already in use by container...여러 번 시도해도 같은 오류가 계속되었고, 문제 해결을 위해 자세히 분석해 보았습니다.
원인 분석
문제를 자세히 살펴보니 크게 세 가지 원인이 있었습니다:
1. 시스템 경로 설정 문제
첫 번째 오류는 supabase CLI가 시스템 경로(PATH)에 등록되지 않아 발생한 것이었습니다. PowerShell이나 CMD에서 직접 실행하려면 글로벌 설치가 필요했습니다.
2. Docker 데몬 TCP 설정 부재
두 번째 오류의 핵심은 "WARNING: analytics requires docker daemon exposed on tcp://localhost:2375" 메시지였습니다. Supabase CLI가 Docker와 통신하기 위해 TCP 포트 2375를 통한 접근이 필요한데, 이 설정이 되어있지 않았습니다.
3. 컨테이너 충돌 문제
"Container name is already in use" 오류는 이전에 생성된 컨테이너와 이름이 충돌한다는 의미입니다. 하지만 Docker 대시보드에서는 해당 컨테이너가 보이지 않는 상태였습니다. 이는 Docker의 내부 상태와 실제 시스템 상태가 일치하지 않아 발생한 문제였습니다.
해결 방법
각 문제에 대한 해결 방법을 하나씩 적용해 보았습니다.
1. Docker Desktop 설정 변경
가장 중요한 해결책은 Docker 데몬을 TCP 포트에 노출시키는 것이었습니다:
- Docker Desktop을 실행합니다
- 우측 상단의 설정(⚙️) 아이콘을 클릭해 설정 메뉴를 엽니다
- 일반(General) 섹션에서 "Expose daemon on tcp://localhost:2375 without TLS" 옵션을 체크합니다
- 'Apply & Restart' 버튼을 클릭하여 Docker를 재시작합니다
이 설정은 Supabase CLI가 Docker API와 통신할 수 있게 해주는 핵심 설정입니다. 보안에 민감하다면 개발이 끝난 후에는 해제하는 것이 좋습니다.
2. Supabase 데이터 초기화
다음으로 기존 Supabase 설정과 컨테이너를 정리했습니다:
1# 백업 없이 Supabase 중지
2npx supabase stop --no-backup
3
4# 상태 확인
5npx supabase status
6
7# 다시 시작
8npx supabase start이 과정에서 --no-backup 옵션을 사용하면 기존 데이터를 모두 삭제하므로, 중요한 로컬 데이터가 있다면 백업을 먼저 진행해야 합니다.
3. 시스템 경로 설정 (선택사항)
매번 npx를 통해 실행하는 것이 번거롭다면, Supabase CLI를 글로벌로 설치할 수 있습니다:
1npm install -g supabase설치 후에는 직접 supabase 명령어를 사용할 수 있게 됩니다. 다만 CLI 버전이 프로젝트마다 다를 수 있으므로, 팀 프로젝트에서는 npx를 통한 실행이 더 안전할 수 있습니다.
추가 문제 해결 방법
위의 방법으로 대부분의 문제가 해결되지만, 여전히 어려움이 있을 경우 다음 사항을 확인해보세요:
1. WSL2와 Docker의 네트워크 설정
Windows에서 WSL2를 사용하는 경우, WSL과 Docker 간의 네트워크 설정이 문제일 수 있습니다. 이 경우 다음을 시도해보세요:
- Docker Desktop 설정에서 WSL 통합 옵션 확인
- PowerShell이 아닌 WSL 터미널에서 Supabase 명령 실행
2. Windows 방화벽 설정
포트 2375가 방화벽에 의해 차단되면 Supabase CLI가 Docker와 통신할 수 없습니다:
- Windows 보안 센터 > 방화벽 및 네트워크 보호 열기
- '앱이 방화벽을 통해 통신하도록 허용' 클릭
- Docker Desktop이 모든 네트워크에서 허용되어 있는지 확인
3. Docker 컨테이너 상태 확인 및 정리
모든 Docker 컨테이너를 확인하고 필요 시 정리합니다:
1# 모든 컨테이너 목록 확인 (중지된 컨테이너 포함)
2docker container ls -a
3
4# 특정 컨테이너 강제 삭제
5docker rm -f [컨테이너_ID]
6
7# 모든 중지된 컨테이너 삭제
8docker container prune
9
10# Docker 시스템 정리 (주의: 이미지, 볼륨 등 미사용 리소스 모두 삭제)
11docker system prune -a마지막 명령어는 모든 미사용 Docker 리소스를 제거하므로 신중하게 사용해야 합니다.
실제 적용 사례
제 경우 Docker 데몬 TCP 설정이 가장 큰 문제였습니다. 이전에는 Docker와 다른 도구들을 함께 사용할 때 이런 설정이 필요하다는 것을 몰랐어요.
설정을 변경한 후에도 컨테이너 충돌 문제가 남아있었는데, docker system prune 명령으로 전체 시스템을 정리하고 나서야 모든 것이 정상적으로 작동하기 시작했습니다.
특히 Windows에서 개발할 때는 이런 환경 설정 문제가 더 자주 발생하는 것 같습니다. 맥이나 리눅스 환경에서는 상대적으로 이런 문제가 적게 발생한다고 합니다.
마무리
Supabase 로컬 개발 환경 구축 시 발생하는 대부분의 문제는 Docker 설정과 관련이 있습니다. 특히 Docker 데몬의 TCP 노출 설정이 가장 중요한 부분이었습니다.
처음에는 이런 문제들이 복잡하고 어렵게 느껴질 수 있지만, 한 번 설정해두면 이후에는 원활하게 개발을 진행할 수 있습니다.
이 글이 Supabase를 시작하는 다른 개발자분들에게 도움이 되길 바라며, 혹시 다른 문제나 해결 방법을 알고 계신다면 댓글로 공유해주시면 감사하겠습니다! 🙌
함께 성장하는 개발 커뮤니티가 되길 바랍니다!