[Docker] next.js를 Docker로 배포하기 with multi-stage 빌드

📌 목차

1. Dockerfile 작성하기 (Single-stage Dockerfile)
2. Multi-stage 빌드를 통한 이미지 최적화
3. .dockerignore로 불필요한 파일 제거
4. 주요 Docker 명령어
5. Reference

 
사내 서비스 프로젝트 프론트엔드 개발을 맡으면서 CI를 구축해 볼 수 있는 기회가 생겼다.
현재 개발중인 서비스는 next.js 기반으로 이루어져 있다. 내가 맡은 역할은 Dockerfile을 생성하여 도커 이미지를 빌드하여 Teamcity에 연동하는 것이다. 이 과정에서 특정 브랜치에 업데이트 발생 시, 도커 이미지를 빌드 후 사내 저장소에 push 하도록 하는 과정까지는 내가 맡았다. 최신 이미지 태그를 가져와 서버를 업데이트 하는 작업은 다른 개발자 선배님이 연동하시기로 했다.
 

Dockerfile 작성하기

먼저, next.js 프로젝트 ROOT에 Dockerfile을 추가한다.

my-nextjs-app/
├── Dockerfile          ✅ 프로젝트 루트에 위치
├── package.json
├── yarn.lock
├── public/
├── pages/ or app/
├── ...

 
추가한 Dockerfile에 코드를 작성한다.

# Node.js 환경 설정
FROM node:20-alpine

# 작업 디렉토리 설정
WORKDIR /app

# 패키지 매니저 설정 파일 복사 및 의존성 설치
COPY package.json yarn.lock ./
RUN yarn install

# 전체 소스 코드 복사
COPY . .

# 애플리케이션 빌드
RUN yarn build

# 컨테이너에서 노출할 포트
EXPOSE 3000

# 앱 실행 명령어
CMD ["yarn", "start"]

 

alpine이란?

Alpine Linux는 보안, 단순성, 리소스 절약에 초점을 맞춘 초경량 리눅스 배포판

 
장점

이미지 크기 작음	Alpine 기반 Node.js 이미지는 약 30~40MB대. 기본 Debian 기반은 300MB 이상.
보안성 높음	최소한의 패키지로 구성되어 공격 표면이 작음.
빠른 배포 및 빌드	이미지가 작아 네트워크 전송 속도 및 CI/CD 속도 향상.
커스터마이징 유리	불필요한 패키지가 없어 필요한 것만 설치해서 슬림하게 유지 가능.

 
주의점

glibc 미포함	Alpine은 musl libc를 사용함. 일부 라이브러리는 glibc 필요해서 충돌 가능.
빌드 환경 문제	native addon을 사용하는 npm 패키지는 alpine에서 빌드 시 에러가 날 수 있음. 예: sharp, bcrypt
디버깅 도구 부족	기본 이미지에 bash, curl, wget, vim 등이 없음. 필요한 경우 직접 설치해야 함.

 

도커 이미지 빌드하기

위에서 작성한 Dockerfile을 명령어를 통해 docker 이미지를 빌드한다.
나의 경우 이미 docker 설치 및 환경 설정이 되어있는 상황이었기 때문에, docker 설치가 되어 있지 않다면 설치가 사전에 필요하다.
docker 설치 및 환경 설정이 끝나면 다음 명령어를 통해 이미지를 빌드한다.

docker build -t [도커 이미지 이름] .

# 예시
# docker build -t cattower-front .

 

빌드 된 이미지 확인

docker images | grep [도커 이미지 이름]

# 예시
# docker images | grep cattower-front

 

 
내가 생성한 빌드 이미지의 경우 3.82GB의 크기를 가지고 있으며, 몇 분 전 생성 되었음을 확인할 수 있었다.
이 명령어 외에도 images 목록을 보는 명령어는 다음과 같다.

docker image ls

 

생성한 이미지를 컨테이너로 실행시켜보기

docker run -d -p [외부에서 통신하기 위한 포트]:3000 [도커 이미지 이름]

# 주의 사항
# 3000번의 경우 dockerfile에서 expose 한 port번호를 적는 것!

# 예시
# docker run -d -p 80:3000 cattower-front
# local에서 할 경우 localhost:80으로 접속시 확인 가능하다.

 

컨테이너가 잘 실행되고 있는지 확인

docker ps

 

실행시킨 컨테이너 중지 / 삭제하기, 이미지 삭제하기

docker stop [컨테이너 ID]
docker rm [컨테이너 ID]
docker image rm [이미지 이름]

 
 

Docker 이미지 크기를 어떻게 줄일 수 있을까?

도커 이미지 생성 시 너무 오래걸려서 해당 이미지 크기를 줄일 수 있으면 줄이는게 좋지 않을까 라는 생각을 했다.
도커 공식문에서 경량화 관련 문서를 발견할 수 있었다.
도커 이미지를 줄이고 싶으면 multi-stage-builds를 사용하거나  .dockerignore 사용하는 법 등을 best practices로 소개하고 있다.
(하이퍼링크를 따라가면 공식 문서를 확인할 수 있다.)
 
나는 공식문서를 참고하여  다음 2가지 방법을 통해 경량화를 시도하였다.

1. Multi-stage 빌드를 통한 이미지 최적화
2. .dockerignore로 불필요한 파일 제거

 

1. Multi-stage 빌드를 통한 이미지 최적화

위에서 작성했던 단일 빌드 이미지의 단점은 node_modules, 테스트 코드, 개발 도구까지 포함되어 있어 이미지 크기가 크다는 단점이 존재한다. 이를 해결하기 위해 multi-stage 빌드를 아래 코드를 통해 Dockerfile에 적용한다.

###########################################
# 🛠️ 1단계: 빌드 스테이지 (Build Stage)
# - 애플리케이션 소스 코드를 빌드하고,
# - 런타임에 필요한 산출물만 추출
###########################################
FROM node:20-alpine AS builder

# 작업 디렉토리 설정
WORKDIR /app

# 의존성 설치를 위한 패키지 파일 복사
COPY package.json yarn.lock ./

# lockfile을 기반으로 의존성 설치 (재현 가능한 빌드)
RUN yarn install --frozen-lockfile

# 전체 소스 코드 복사
COPY . .

# 애플리케이션 빌드 (.next, public 등 생성)
RUN yarn build

###########################################
# 🚀 2단계: 프로덕션 런타임 스테이지
# - 실제 실행에 필요한 최소한의 파일만 포함
# - 이미지 크기를 최소화하여 보안 및 성능 개선
###########################################

FROM node:20-alpine

# 작업 디렉토리 설정
WORKDIR /app

# 빌드된 결과물 및 실행에 필요한 파일만 복사
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/public ./public

# 애플리케이션이 사용하는 포트 개방
EXPOSE 3000

# 애플리케이션 실행 명령어
CMD ["yarn", "start"]

 

multi-stage 적용 후 이미지 크기 비교

전 : single-stage 빌드
후: multi-stage 빌드

 
해당 코드를 적용 후 다시 이미지 크기를 확인해 보았다.

전 - single-stage 빌드 (3.82GB)

후 - multi-stage 빌드 (1.34GB)

 
3.82GB에서 1.34GB로 약 64.9% 이미지가 감소했다.

2.  .dockerignore 로 불필요한 파일 제거

다음 방법으로는 .dockerignore 파일을 추가하여 불필요한 파일을 제거하는 방법이다.

my-nextjs-app/
├── Dockerfile          ✅ 프로젝트 루트에 위치
├── .dockerignore       ✅ Dockerfile과 같은 위치
├── package.json
├── yarn.lock
├── public/
├── pages/ or app/
├── ...

 
Dockerfile과 같이 next.js의 프로젝트 ROOT 경로에 .dockerignore를 추가한다.

## .dockerignore

node_modules
.next

.git
.gitignore
*.log
.vscode
.idea
*.tsbuildinfo
.DS_Store

coverage
__tests__

 

.dockerignore 적용 후 이미지 크기 비교

전 : multi-stage만 적용
후 : multi-stage + .dockerignore 적용

 

전 - multi-stage만 적용된 이미지 (1.34GB)

 

후 - multi-stage + .dockerignore 적용한 이미지 (1.08GB)

1.34GB에서 1.08GB로 약 19.4% 이미지가 감소했다.

 

최적화 전 /후 비교

최적화 전의 이미지 크기는 3.82GB였고, 두 가지 방법의 최적화를 거쳐 최종적으로는 1.08GB가 되어 약 72% 감소하였다.

 

 

주요 Docker 명령어

마지막으로 Docker 명령어를 정리해 보았다.

## 도커 이미지 빌드
docker build -t [이미지 이름] .

## 도커 이미지 크기 확인
docker images | grep [이미지 이름]

## 현재 실행 중인 컨테이너 중지
docker stop $(docker ps -q)

## 현재 실행 중인 이미지 확인
docker ps

## 포트 매핑을 포함하여 새로 실행
docker run -p 3000:3000 [이미지 이름]

## 도커 이미지 목록
docker image ls

## 모든 컨테이너 강제 삭제
docker rm -f $(docker ps -aq)

## 이미지 삭제
docker rmi [이미지 이름]

 

Reference

---

https://github.com/vercel/next.js/blob/canary/examples/with-docker/Dockerfile
https://promisingmoon.tistory.com/229#요약 -1
https://jaeseo0519.tistory.com/264#1. Health check를 지원하는 Docker Image 빌드-1
https://creboring.net/blog/how-docker-divide-image-layer/
https://medium.com/@hee98.09.14/docker-layer와-cache-574c12a1e9f7
https://velog.io/@gnoeyah/Next.js프로젝트를-Docker에-올리라는-미션을-받았다
https://frorong.tistory.com/entry/Docker-NextJS-배포를-위한-도커-컨테이너화
https://oliveyoung.tech/2022-05-03/How-to-Set-up-Build-Process-with-Teamcity/
https://docs.docker.com/build/building/best-practices/