사전 준비

이 단계는 한 번만 하면 됩니다. 이미 설치돼 있는 항목은 건너뛰면 됩니다.

처음 보는 명령이 절반 이상이라면 비개발자용 시작의 “어떤 분을 염두에 두고 썼나” 단락을 한 번 보고 와 주세요. 매뉴얼이 가정하는 학습 수준이 거기에 정리돼 있습니다.

운영체제별 차이

항목	macOS	Windows	Linux
사용하는 터미널	`Terminal.app` 또는 iTerm2를 씁니다.	WSL2 위의 Ubuntu를 권장합니다. PowerShell도 가능하지만 안내가 길어집니다.	배포판이 제공하는 셸을 씁니다.
검증 상태	검증되었습니다.	WSL2를 먼저 설치한 다음 그 안에서 모든 명령을 실행합니다.	검증되었습니다.
Docker	Docker Desktop을 씁니다.	Docker Desktop을 설치하고 WSL2 통합을 켭니다.	docker engine을 씁니다.

Windows에서는 WSL2 설치 안내를 먼저 끝낸 다음 이쪽으로 돌아오세요. 이 매뉴얼의 모든 명령은 WSL2 위 Ubuntu 셸 안에서 실행한다고 가정합니다.

1) Node.js 20 이상

macOS와 Linux는 nvm 권장

터미널을 열고 한 줄씩 실행합니다.

# nvm (Node Version Manager) 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 새 터미널을 열거나, 다음 두 줄을 붙여 넣어 nvm을 지금 바로 활성화합니다
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Node 20을 설치한 다음 사용합니다
nvm install 20
nvm use 20

설치 검증

node --version    # v20.x.x 가 출력되어야 정상입니다
npm --version     # 10.x.x 와 비슷한 숫자가 출력되면 정상입니다

둘 중 하나라도 아무것도 출력되지 않는다면 09-troubleshooting.md의 “Node가 설치되지 않습니다” 항목으로 갑니다.

새 터미널에서 node --version 이 다시 출력되지 않는다면 nvm 활성화 두 줄이 셸 시작 파일에 들어가지 않은 상태입니다. macOS와 Linux는 기본 셸에 따라 파일이 다릅니다. zsh 라면 ~/.zshrc 이고, bash 라면 ~/.bashrc 입니다. 그 파일을 열고 nvm 설치 출력 끝부분에 보였던 export NVM_DIR=... 두 줄이 들어가 있는지 확인하세요. 없으면 손으로 붙여 넣고 새 터미널을 엽니다.

2) git

macOS

xcode-select --install

이 명령은 git만 따로 설치하지 않고 Apple의 Command Line Tools 묶음을 설치합니다. 작은 대화 상자가 떠서 동의를 받고 설치가 시작됩니다. git이 이미 설치돼 있으면 안내 메시지만 한 줄 띄우고 끝납니다. 보통 5분 안쪽이면 끝납니다.

Linux: Ubuntu와 Debian

sudo apt update && sudo apt install -y git

WSL2 위 Ubuntu에서도 같은 명령을 그대로 씁니다. WSL2의 Ubuntu는 일반 Ubuntu와 패키지 시스템이 동일합니다.

설치 검증

git --version    # git version 2.x.x 가 출력됩니다

git에 본인 정보 한 번 등록

git config --global user.name "Your Name"
git config --global user.email "your@example.com"

이 이름과 이메일이 앞으로 만드는 커밋의 작성자로 기록됩니다. 회사 메일과 분리하고 싶다면 나중에 저장소별로 따로 설정하면 되니, 지금은 사용 가능한 정보를 넣어 두면 됩니다.

3) Docker

이 base는 로컬에서 Supabase를 띄울 때 Docker가 필요합니다. supabase start 명령이 Postgres와 Auth, Storage를 컨테이너로 띄우기 때문입니다. Docker가 없으면 그 단계에서 막힙니다.

macOS와 Windows: Docker Desktop

docker.com/products/docker-desktop 에서 본인 운영체제에 맞는 설치 파일을 받아 설치합니다. 설치가 끝나면 한 번 실행해서 회원가입과 로그인까지 끝내 둡니다. Docker Desktop이 실행 중이어야 supabase start 가 컨테이너를 띄울 수 있습니다.

Windows에서는 Docker Desktop 설정의 Resources → WSL Integration 에서 본인 Ubuntu 배포판 토글을 켜 두세요. 그래야 WSL2 안의 터미널에서 docker 명령이 동작합니다.

Linux: docker engine

sudo apt update && sudo apt install -y docker.io
sudo usermod -aG docker $USER     # sudo 없이 docker 명령을 쓰려면 필요합니다

마지막 줄을 실행한 다음 한 번 로그아웃하고 다시 들어와야 그룹이 적용됩니다.

설치 검증

docker --version   # Docker version 24.x 또는 그 이상이 출력됩니다
docker ps          # 빈 표가 출력되면 정상입니다. 권한 에러가 뜨면 위 usermod 가 적용되지 않은 상태입니다

docker ps 가 권한 에러로 막히면 macOS에서는 Docker Desktop이 실행 중인지 확인하고, Linux에서는 usermod 실행 후 다시 로그인했는지 확인합니다. 처음에는 보통 이 둘 중 하나가 원인입니다.

4) Supabase 계정과 CLI

계정 만들기

supabase.com 에 GitHub 계정으로 가입합니다. 무료 요금제로 충분합니다. 가입이 끝나도 지금 당장 새 프로젝트를 만들 필요는 없습니다. 그 작업은 04-real-backend.md 단계에서 합니다.

이 단계에서 해 둘 것은 가입까지입니다. 계정이 있어야 다음 단계의 supabase login 이 동작합니다.

CLI 설치

# macOS
brew install supabase/tap/supabase

# Linux와 WSL2
curl -fsSL https://github.com/supabase/cli/releases/latest/download/supabase_linux_amd64.tar.gz \
  | sudo tar -xz -C /usr/local/bin supabase

설치 검증

supabase --version
supabase login                  # 브라우저가 열리면서 계정을 인증합니다

supabase login 이 끝나면 CLI가 본인 계정에 연결됩니다. 한 번만 하면 됩니다.

5) Stripe 계정

stripe.com 에 가입한 다음 대시보드 오른쪽 위의 Test mode 토글을 켭니다. test mode 가 켜진 상태에서는 실제 결제가 일어나지 않고 테스트용 카드 번호로 결제 흐름만 돌려볼 수 있습니다. 가입 직후 기본값이 test mode 이지만 한 번 확인해 두세요.

대시보드 왼쪽 메뉴의 Developers → API keys 에 두 종류의 키가 있습니다. pk_test_... 로 시작하는 Publishable key 와 sk_test_... 로 시작하는 Secret key 입니다. 두 키를 메모해 둡니다. 04-real-backend.md 의 끝이나 05-customize-design.md 이후 결제 흐름을 켤 때 사용합니다.

운영 환경 결제를 받기 전까지는 test mode 만 씁니다. 실제 사업자 등록과 결제 활성화는 본인 SaaS가 실사용자에게 갈 때 결정합니다. 이 매뉴얼의 범위는 test mode 안에서 끝까지 한 바퀴 돌려 보는 데까지입니다.

6) Claude Code

공식 설치 안내는 docs.claude.com/ko/docs/claude-code/quickstart 에 있습니다. 설치한 다음 claude 를 한 번 실행해 로그인하거나 API 키를 등록합니다.

claude --version

버전 번호가 출력되면 준비가 끝났습니다. Claude Code 대신 OpenAI Codex CLI를 써도 됩니다. 그 경우 진입점은 저장소 루트의 AGENTS.md 이고 같은 흐름이 그대로 적용됩니다. 처음이라면 Claude Code를 권합니다.

7) 선택 사항: 코드 에디터

코드가 만들어지는 모습을 보고 싶다면 VS Code 가 무난합니다. AI가 코드를 다 써 주기 때문에 에디터가 꼭 필요하지는 않습니다. 다만 방금 무슨 일이 일어났는지 들여다보고 싶을 때는 있는 편이 편합니다.

여섯 항목이 모두 갖춰졌다면 02-clone-and-install.md로 갑니다.