🐳 웹 프론트엔드 프로젝트(Next.js)를 Docker로 배포하기

✅ 1. Next.js 프로젝트 생성

npx create-next-app@latest

💡 실행 후 프로젝트 이름, 타입스크립트 여부 등을 설정합니다.

 

---

✅ 2. Dockerfile 작성

📄 Dockerfile

# 1단계: 빌드용 스테이지
FROM node:20-alpine AS builder

WORKDIR /app

COPY . .

RUN npm install
RUN npm run build

# 2단계: 실행용 스테이지 (경량화)
FROM node:20-alpine

WORKDIR /app

COPY --from=builder /app ./

EXPOSE 3000

CMD ["npm", "start"]

🛠️ 멀티스테이지 빌드로 불필요한 파일 없이 최종 실행 이미지 생성
🔒 builder 는 빌드에만 사용되고 실제 실행 이미지에는 포함되지 않음

 

🔍 멀티스테이지 빌드란?

• 빌드 전용 스테이지( builder )와 실행 전용 스테이지를 나누는 방식입니다.
• 이유 : 빌드할 때 필요한 도구( devDependencies, 소스파일 등)는 실행할 때 필요 없음 -> 이미지 사이즈 낭비!
• 그래서 1단계에서 빌드 후, 필요한 산출물( .next, node_modules, package.json ) 만 다음 단계로 복사 합니다.

실행용 스테이지

• COPY --from=builder :위에서 만든 결과물만 가져옴
• 결과적으로 불필요한 파일 ( src, .git, 테스트 코드 등)은 포함되지 않음
• 최소화된 경량 이미지 생성 ( 보통 수백 MB 절감 가능 )

 

---

✅ 3. .dockerignore 작성

📄 .dockerignre

node_modules
npm-debug.log
.next

🚫 node_modules, .next 등은 컨테이너 빌드 시 불필요하므로 제외

 

---

✅ 4. Docker 이미지 빌드

docker build -t nextjs-app .

nextjs-app 이라는 이름으로 이미지 생성

 

---

✅ 5. 컨테이너 실행

docker run -d -p 80:3000 nextjs-app

외부 3000 -> 내부 컨테이너 80으로 포워딩

 

---

✅ 6. 브라우저에서 확인

http://localhost(:80) 생략가능

Next.js 앱 정상 구동 시 기본 환영 페이지 확인 가능

 

---

✅ 7. 개발 중 Docker 사용 (선택)

개발 중에는 Dockerfile.dev 를 사용하면 효율적입니다.

📄 Dockerfile.dev

FROM node:20-alpine

WORKDIR /app

COPY . .

RUN npm install

EXPOSE 3000

ENTRYPOINT [ "npm" , "run", "dev"]

docker build -f Dockerfile.dev -t nextjs-dev .
docker run -p 80:3000 nextjs-dev

🧪 개발 서버 (npm run dev) 실행을 위한 설정

 

🔍 왜 따로 만들까?

•  위 Dockerfile 은 npm run build 를 실행하기 때문에 프로덕션 실행용
• 개발할 땐 코드 수정 후 바로 반영되도록 **개발 서버 ( npm run dev )**를 써야 합니다.
• 그래서 CMD ["npm", "run", "dev"] 로 개발 서버를 실행합니다.
• 이럴 대는 **볼륨 마운트(-y)**까지 추가하면 더 좋습니다.

 

---

✅ 정리

항목	내용
빌드 이미지	npm run build 포함
실행 이미지	가볍게 최적화
개발용	Dockerfile.dev 따로 운영
포트	80:3000으로 매핑