Docker 개발

Docker Compose를 사용해 web, api, PostgreSQL을 통합 실행하는 방법입니다.

사전 준비

• Docker Engine + Docker Compose v2
• .env.dev 파일 (프로젝트 루트)

DB_PASSWORD=example_password
VITE_API_URL=http://localhost:3000
NODE_ENV=development
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
JWT_SECRET=your-jwt-secret-at-least-32-chars

실행

# 일반 실행
pnpm docker:dev

# 이미지 재빌드 후 실행
pnpm docker:dev:build

# DB 스키마 적용 (최초 1회 또는 마이그레이션 추가 후)
pnpm docker:db:setup

# Prisma Studio (DB 브라우저)
pnpm docker:prisma:studio
# → http://localhost:5555

# 종료
pnpm docker:down

루트 package.json 스크립트:

"docker:dev": "docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.dev up",
"docker:db:setup": "pnpm docker:prisma:generate && pnpm docker:prisma:migrate",
"docker:prisma:studio": "docker compose ... run --rm -p 5555:5555 api ... prisma studio"

서비스 구성

web (포트 3001)

• Dockerfile: apps/web/Dockerfile.dev
• turbo prune web --docker로 최소 의존성만 설치
• 소스 볼륨 마운트로 HMR 지원
• VITE_API_URL로 api 주소 주입

api (포트 3000)

• Dockerfile: apps/api/Dockerfile.dev
• DATABASE_URL로 PostgreSQL 연결
• Google OAuth + JWT 환경 변수 전달
• DB healthcheck 통과 후 기동

db (PostgreSQL 17)

• 사용자: postgres
• DB: mydb
• 볼륨: postgres_data (데이터 영속)

아키텍처 다이어그램

캔버스 노드 문서는 api DB Node 테이블에 저장됩니다. web localStorage에는 UI 설정만 persist됩니다.

docs 앱

현재 Docker Compose에는 docs 서비스가 포함되어 있지 않습니다. 문서 사이트는 로컬에서 별도 실행하세요:

pnpm --filter docs dev

프로덕션

pnpm docker:prod

docker-compose.prod.yml과 .env.prod를 사용합니다.

트러블슈팅

증상	해결
api가 db 연결 실패	db healthcheck 완료 대기, DB_PASSWORD 일치 확인
Prisma Client 오류	pnpm docker:db:setup 실행
Google OAuth 실패	OAuth 리디렉션 URI, GOOGLE_CLIENT_* 값 확인
web HMR 안 됨	볼륨 마운트 경로 확인, 컨테이너 재시작
포트 충돌	3000/3001/5555 사용 프로세스 확인
로그인 후 쿠키 미전달	fetch에 credentials: 'include', CORS origin 일치 확인
git stash 후 파일 잔留	Docker가 root/nobody 소유로 만든 파일 → sudo chown -R $USER:$USER apps/
Prisma Studio --hostname 오류	Prisma 7에서는 미지원. pnpm docker:prisma:studio 스크립트 사용 (--browser none만)

다음 단계

캔버스 사용법 →