“내 컴퓨터에서는 작동한다"는 말은 모든 개발자가 너무나 잘 알고 있는 말입니다. Docker는 애플리케이션과 해당 종속성을 휴대용 컨테이너에 패키징하여 이 문제를 해결합니다. 이 문서에서는 Docker를 사용하여 로컬 개발 환경을 설정하는 방법을 안내합니다.

세 가지 핵심 개념

• Dockerfile: 컨테이너에 대한 청사진 — 사용할 기본 이미지와 설치할 항목.
• docker-compose.yml : 여러 컨테이너(웹 서버, 데이터베이스, 캐시 등)를 함께 관리하기 위한 구성 파일입니다.
• 볼륨 마운트: 컨테이너가 호스트 시스템의 파일을 참조할 수 있도록 합니다. 핫 리로드에 필수적입니다.

docker-compose를 사용한 다중 서비스 설정

일반적인 프런트엔드 + 백엔드 + 데이터베이스 설정은 단일 docker-compose.yml에서 정의할 수 있습니다.

version: "3.9"
services:
  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    volumes:
      - ./frontend:/app
      - /app/node_modules
    command: npm run dev

  backend:
    build: ./backend
    ports:
      - "8000:8000"
    volumes:
      - ./backend:/app
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/app

  db:
    image: postgres:16
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

핵심 사항

• ./frontend:/app과 같은 볼륨 마운트는 호스트 소스 코드를 컨테이너에 동기화합니다. 호스트의 변경 사항은 컨테이너 내부에 즉시 반영되어 핫 리로드가 계속 작동합니다.
• node_modules에 대한 익명 볼륨: /app/node_modules 항목은 호스트와의 동기화를 방지하여 Windows와 Linux 간의 기본 모듈 호환성 문제를 방지합니다.
• 환경 변수: environment 블록을 통해 데이터베이스 연결 문자열과 같은 구성을 전달합니다.

개발자 친화적인 Dockerfile

개발을 위해 별도의 Dockerfile을 유지하는 것이 일반적인 관행입니다.

FROM node:20-alpine

WORKDIR /app

# Install dependencies first (leverage layer caching)
COPY package*.json ./
RUN npm install

# Source code is volume-mounted, so no COPY needed
CMD ["npm", "run", "dev"]

비결은 이미지에 COPY 소스 코드를 삽입하지 않는 것입니다. 대신 docker-compose.yml의 volumes을 통해 호스트 디렉터리를 마운트하세요. 이렇게 하면 컨테이너를 다시 빌드하지 않고도 코드 변경 사항이 즉시 적용됩니다.

팀 일관성

로컬 개발에서 Docker의 진정한 가치는 모든 사람이 동일한 환경을 실행한다는 것입니다. 몇 가지 팀 규칙이 큰 도움이 됩니다.

• docker-compose.yml 및 Dockerfile을 Git에 커밋합니다.
• .gitignore에 .env(비밀번호)을 추가하고 저장소에 .env.example를 포함합니다.
• Docker에 익숙하지 않은 팀원이 쉽게 시작할 수 있도록 Makefile 또는 npm scripts에 래퍼 명령을 제공합니다.

up:
	docker compose up -d
down:
	docker compose down
build:
	docker compose build
logs:
	docker compose logs -f

일반적인 함정

• 성능: 특히 WSL2가 없으면 Windows에서 파일 마운트가 느려질 수 있습니다. WSL2에서 Docker Desktop을 실행하거나 Mutagen과 같은 동기화 도구를 고려해보세요.
• 포트 충돌: 여러 프로젝트가 동일한 포트(예: 3000)를 사용하는 경우 ports 구성에서 호스트 측 포트를 변경합니다(예: "3001:3000").
• 볼륨 정리: 시간이 지남에 따라 오래된 볼륨이 누적됩니다. docker compose down -v을 실행하여 정리하세요.

요약

로컬 개발에서 Docker의 가장 큰 이점은 재현성과 팀 일관성입니다. docker-compose를 사용하여 볼륨 마운트를 통해 핫 리로드를 유지하면서 여러 서비스를 함께 관리하면 두 가지 장점을 모두 누릴 수 있습니다. 먼저 소규모 프로젝트에서 사용해 본 다음 팀의 전체 작업 흐름으로 확장하세요.