사전 준비

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

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

운영체제별 차이

항목	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 "[email protected]"

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

3) Docker

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

macOS와 Windows — Docker Desktop

docker.com/products/docker-desktop 에서 본인 OS에 맞는 설치 파일을 받아 설치합니다. 설치가 끝나면 한 번 실행해서 회원가입과 로그인까지 끝내 둡니다. 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 에 두 종류의 키가 있습니다. Publishable key (pk_test_... 로 시작) 와 Secret key (sk_test_... 로 시작). 두 키를 메모해 둡니다. 04-real-backend.md 의 끝 또는 05-customize-design.md 이후 결제 흐름을 켤 때 사용합니다.

Production 결제를 받기 전까지는 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로 갑니다.