앞 편(15분 만에 웹앱 골격)은 "빈 폴더 하나를 열어 두고 시작하자"로 출발한다. 그런데 개발이 처음인 사람에게는 그 "빈 폴더를 열 수 있는 상태"를 만드는 일부터가 벽이다. 터미널은 어떻게 켜고, PostgreSQL은 "Docker로 띄운다"는데 Docker는 또 뭐고 어떻게 깔지, Node는 언제 필요한지가 통째로 빠져 있었다.
이 편은 그 빠진 0단계를 채운다. 윈도우를 쓰든 맥을 쓰든, 이 글을 그대로 따라 치면 연재를 시작할 수 있는 작업장이 갖춰진다. 명령은 윈도우(WSL)를 기준으로 적고, 맥이 다른 부분만 따로 표시한다. 개념은 먼저 비유로 잡고, 그다음에 실제 명령을 친다.
오늘 갖출 것 (설치 지도)
순서가 중요하다. 아래를 위에서부터 하나씩 깐다. 각 줄이 왜 필요한지는 바로 뒤에서 푼다.
| 순서 | 무엇을 | 왜 필요한가 | 윈도우 / 맥 |
|---|---|---|---|
| 1 | WSL(우분투) | 윈도우 안에서 리눅스 명령을 쓰기 위한 바닥 | 윈도우만 해당 (맥은 터미널이 이미 리눅스 계열) |
| 2 | 기본 도구 (git, curl 등) | 코드를 받고 내려받는 최소 연장 | 공통 |
| 3 | Docker Engine | PostgreSQL을 "설치 없이" 깔끔하게 띄우는 상자 관리자 | 공통 (설치 방식만 다름) |
| 4 | PostgreSQL 컨테이너 | 연재 내내 쓸 데이터베이스 | 공통 |
| 5 | Node.js | 프론트엔드(Next.js)를 돌리는 런타임 | 공통 |
| 6 | Python | AI 작업용 백엔드(FastAPI)를 돌리는 런타임 | 공통 |
| 7 | Claude Code | 이 연재의 주인공. 코드를 함께 짜는 에이전트 | 공통 |
1. 터미널부터 — 윈도우는 WSL, 맥은 그냥 터미널
이 연재의 모든 명령은 터미널(글자를 쳐서 컴퓨터에 명령하는 검은 창)에서 친다. 맥은 이미 리눅스 계열이라 터미널 앱을 그냥 열면 된다. 문제는 윈도우다. 윈도우의 명령 창은 리눅스와 명령어가 다르기 때문에, 윈도우 안에 리눅스(우분투)를 하나 심어 두는 WSL(Windows Subsystem for Linux: 윈도우용 리눅스 하위 시스템)을 먼저 깐다.
윈도우에서 PowerShell을 관리자 권한으로 열고 한 줄이면 끝난다 (마이크로소프트 공식 가이드).
# 윈도우 PowerShell (관리자)
wsl --install
# 설치 후 재부팅 → 우분투가 자동으로 뜨고 사용자 이름/비밀번호를 한 번 정한다
재부팅하면 우분투 창이 열린다. 이제부터 모든 명령은 이 우분투 창에서 친다 (윈도우 기본 명령 창이 아니다). 맥 사용자는 이 1번을 건너뛰고 터미널 앱에서 그대로 진행하면 된다.
리눅스 명령이 아직 낯설다면, 이 연재를 따라가기 전에pwd,cd,ls,mkdir같은 필수 명령을 먼저 손에 익히는 걸 권한다. 명령 하나하나의 뜻과 쓰임을 스스로 연습하고 점수까지 매겨 주는 셀프 연습 자료를 이 과정에 따로 두었다.
2. 기본 연장 챙기기
우분투(또는 맥)를 처음 열면 코드를 받는 데 필요한 최소 도구부터 깐다. 윈도우/맥이 갈리는 첫 지점이다. 윈도우(우분투)는 apt라는 설치 도구를, 맥은 brew(Homebrew)를 쓴다.
# 윈도우 (WSL 우분투)
sudo apt update
sudo apt install -y git curl
# 맥 — 먼저 Homebrew부터 (없다면). 안내: https://brew.sh
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install git curl
sudo는 관리자 권한으로 실행하라는 뜻이고, apt update는 설치 목록을 최신으로 갱신, apt install이 실제 설치다. 여기서 git(코드의 변경 이력을 시점별로 저장하는 도구)과 curl(주소로 데이터를 받아 오는 도구)을 깔았다.
3. Docker — "설치 없이 앱을 통째로 담는 상자"
앞 편은 PostgreSQL을 "Docker로 띄우는 게 가장 빠르다"고만 하고 지나갔다. 왜 그냥 설치하지 않고 Docker를 쓸까?
PostgreSQL을 내 컴퓨터에 직접 설치하면, 버전이 꼬이거나 다른 프로그램과 충돌하거나, 나중에 지울 때 찌꺼기가 남는다. Docker는 이 문제를 컨테이너라는 규격 상자로 푼다. 화물선을 떠올리면 쉽다. 안에 뭐가 들었든 상자 규격은 똑같아서, 어느 배에 실어도, 어느 항구에 내려도 그대로 돌아간다. PostgreSQL을 이 상자 하나에 담아 두면, 내 컴퓨터를 더럽히지 않고 통째로 띄우고 통째로 지운다.
정리하면 두 단어다.
- 이미지(image): 앱과 그 실행 환경을 통째로 굳혀 둔 "붕어빵 틀". PostgreSQL 이미지 하나면 어디서든 같은 DB가 나온다.
- 컨테이너(container): 그 틀로 찍어 낸 "붕어빵", 즉 실제로 돌아가는 한 개의 앱. 이미지는 하나여도 컨테이너는 여러 개 찍어 낼 수 있다.
Dockerfile(이미지를 만드는 설계도)로 이미지를 굽고(build), 그 이미지 하나로 컨테이너를 여러 개 띄운다(run). 이미지는 하나, 컨테이너는 여럿이라는 관계가 핵심이다.
그런데 이런 의문이 든다. 앱마다 통째로 담는다면, 옛날에 쓰던 가상 머신(컴퓨터 안에 또 하나의 컴퓨터를 통째로 돌리는 방식)과 뭐가 다른가? 핵심은 운영체제(OS)를 통째로 지고 다니느냐에 있다.
위 그림처럼 가상 머신은 앱마다 각자의 운영체제(게스트 OS)를 통째로 얹는다. 무겁고 느리다. 반면 컨테이너는 내 컴퓨터의 운영체제(호스트 OS)를 여럿이 나눠 쓰고, 상자 안에는 앱과 그 실행에 꼭 필요한 것만 담는다. 그래서 컨테이너는 몇 초 만에 뜨고 훨씬 가볍다. 윈도우에서 WSL 위에 Docker를 올리는 구조도 같은 결이다. 윈도우(호스트) 안의 우분투를 바탕 삼아 상자들이 그 위에서 가볍게 돈다.
설치 방식은 윈도우와 맥이 다르다.
# 윈도우 (WSL 우분투) — Docker Engine을 우분투 안에 직접 설치
# 공식 편의 스크립트 (docs.docker.com/engine/install/ubuntu 참고)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
# 매번 sudo 안 붙이려면 내 계정을 docker 그룹에 추가 후 터미널 재시작
sudo usermod -aG docker $USER
맥은 Docker Engine을 직접 깔기보다 Docker Desktop(엔진 + 관리 화면을 묶은 앱)을 설치하는 편이 쉽다 (맥용 설치 안내). 윈도우도 명령줄이 부담되면 Docker Desktop을 쓸 수 있지만, 이 연재는 WSL 안에서 엔진을 직접 쓰는 쪽으로 진행한다 (우분투 설치 문서).
# 맥 — Docker Desktop 설치 후 실행하거나, brew로
brew install --cask docker
# 설치 뒤 Docker Desktop 앱을 한 번 실행해 두어야 엔진이 켜진다
설치가 됐는지 확인한다. 버전이 찍히면 성공이다.
docker --version
docker run hello-world # 성공하면 환영 메시지가 뜬다
4. PostgreSQL 컨테이너 띄우기
이제 Docker로 데이터베이스를 띄운다. PostgreSQL 이미지를 받아 컨테이너 하나를 돌리는 명령은 한 줄이다 (공식 postgres 이미지).
docker run --name study-db \
-e POSTGRES_PASSWORD=devpass \
-e POSTGRES_DB=studydb \
-p 5432:5432 \
-d postgres:16
한 줄씩 뜯어보면 이렇다.
--name study-db: 이 컨테이너의 이름. 나중에 켜고 끌 때 이 이름으로 부른다.-e POSTGRES_PASSWORD=devpass: DB 접속 비밀번호를 환경 변수로 지정 (로컬 개발용이라 단순하게).-e POSTGRES_DB=studydb: 처음부터 만들어 둘 데이터베이스 이름.-p 5432:5432: 컨테이너 안의 5432 포트를 내 컴퓨터의 5432 포트로 연결. 앱이 이 문으로 DB에 접속한다.-d postgres:16: PostgreSQL 16 이미지를 백그라운드(-d)로 실행. 이미지가 없으면 자동으로 내려받는다.
잘 떴는지, 그리고 껐다 켜는 법은 이렇게 확인한다.
docker ps # 돌고 있는 컨테이너 목록 — study-db가 보이면 성공
docker stop study-db # 잠시 끄기 (컴퓨터 끄기 전)
docker start study-db # 다시 켜기 (작업 재개할 때)
이 컨테이너가 연재 내내 쓸 데이터베이스다. 앱에서 접속할 주소는 이 형식이 된다. 이 값은 코드에 박지 말고 .env 파일에 둔다고 앞 편에서 배웠다.
# .env 예시 (코드 밖에 두는 설정값)
DATABASE_URL=postgresql://postgres:devpass@localhost:5432/studydb
5. Node.js와 Python — 두 런타임
프론트엔드(Next.js)는 Node.js 위에서, AI 작업용 백엔드(FastAPI)는 Python 위에서 돈다. 둘 다 깐다.
# 윈도우 (WSL 우분투) — Node.js LTS
# NodeSource 저장소 (github.com/nodesource/distributions 참고)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs
# Python은 우분투에 대개 있지만, pip과 venv를 챙긴다
sudo apt install -y python3 python3-pip python3-venv
# 맥
brew install node python
버전이 찍히면 준비 완료다.
node -v # 예: v20.x
npm -v # Node와 함께 오는 패키지 설치 도구
python3 --version
6. Claude Code 설치
마지막으로 이 연재의 주인공을 깐다. Claude Code는 npm으로 설치한다 (공식 설치 문서).
npm install -g @anthropic-ai/claude-code
# 프로젝트 폴더로 이동한 뒤 실행하면 첫 로그인 안내가 뜬다
claude
처음 실행하면 로그인 절차를 한 번 거친다. 이후부터는 프로젝트 폴더에서 claude만 치면 에이전트가 그 폴더를 작업장으로 삼는다.
확인 — 작업장이 다 갖춰졌는가
아래 명령이 모두 버전이나 정상 응답을 내면, 앞 편의 "빈 폴더 하나를 열어 두고 시작하자"를 이제 진짜로 시작할 수 있다.
git --version
docker ps # study-db 컨테이너가 떠 있는가
node -v
python3 --version
claude --version
하나라도 오류가 나면, 그 줄에 해당하는 위 단계로 돌아가 다시 확인한다. 특히 docker ps에서 아무것도 안 보이면 4번의 docker start study-db로 컨테이너를 다시 켠다.
여기까지가 0단계다. 이제 1편(15분 만에 웹앱 골격)으로 넘어가면, 방금 갖춘 이 작업장 위에서 첫 골격이 세워진다. 준비가 끝났으니, 만드는 일만 남았다.