멀티 스테이지 빌드로 도커 이미지 크기 줄이기 — 빌드 도구는 두고 결과물만 담기

한 줄 요약

멀티 스테이지 빌드는 Dockerfile 하나에서 빌드 단계와 실행 단계를 나누는 방법이에요. 최종 이미지에는 실행에 필요한 결과물만 남아요.

멀티 스테이지 빌드

---

1. 핵심 개념

 

1.1 멀티 스테이지 빌드란

공식 문서에 따르면 멀티 스테이지 빌드는 Dockerfile 안에서 FROM을 여러 번 쓰는 방식이에요.

• FROM 한 줄이 새로운 **스테이지(단계)**의 시작이에요.
• 스테이지마다 다른 베이스 이미지를 쓸 수 있어요.
• 앞 스테이지의 결과물 중 필요한 것만 골라 다음 스테이지로 복사해요.

스테이지(stage): Dockerfile 안에서 FROM으로 시작하는 하나의 작업 구간이에요.

 

1.2 왜 중요한가

Java 앱을 빌드하려면 JDK와 빌드 도구가 필요해요. 하지만 실행에는 JRE와 jar 파일만 있으면 돼요.

멀티 스테이지 빌드를 쓰면 빌드 도구가 최종 이미지에 들어가지 않아요.

• 최종 이미지에 불필요한 파일이 줄어들어요.
• 이미지 안의 구성 요소가 적어져 관리 대상이 줄어요.
• 별도 빌드 스크립트 없이 Dockerfile 하나로 끝나요.

JDK: Java 프로그램을 개발·빌드하는 도구 모음이에요.

JRE: Java 프로그램을 실행만 하는 환경이에요.

---

2. 쉽게 이해하기

멀티 스테이지 빌드는 가구 공장과 같아요.

• 공장(빌드 스테이지)에는 톱, 드릴, 자재가 가득해요.
• 고객에게는 완성된 가구(실행 스테이지)만 배송해요.
• 공구까지 함께 보낼 이유는 없어요.

---

3. 기본 구조

공식 문서 예시를 단순화한 구조예요.

# 1단계: 빌드
FROM golang:1.25 AS build
WORKDIR /src
COPY main.go .
RUN go build -o /bin/hello ./main.go

# 2단계: 실행
FROM scratch
COPY --from=build /bin/hello /bin/hello
CMD ["/bin/hello"]

• AS build: 스테이지에 이름을 붙여요.
• COPY --from=build: build 스테이지의 파일을 가져와요.
• 최종 이미지는 마지막 스테이지만으로 만들어져요. Go 컴파일러는 남지 않아요.

스테이지에 이름을 붙이지 않으면 0, 1처럼 번호로 참조해요. 이름을 쓰면 순서가 바뀌어도 참조가 깨지지 않아요.

---

4. 실습: Spring Boot(Gradle) 앱에 적용하기

# 1단계: 빌드 스테이지 (JDK 포함)
FROM eclipse-temurin:21-jdk AS build
WORKDIR /app

COPY gradlew .
COPY gradle gradle
COPY build.gradle settings.gradle ./
COPY src src

RUN chmod +x gradlew && ./gradlew bootJar --no-daemon

# 2단계: 실행 스테이지 (JRE만 포함)
FROM eclipse-temurin:21-jre
WORKDIR /app

COPY --from=build /app/build/libs/*.jar app.jar

ENTRYPOINT ["java", "-jar", "app.jar"]

 

4.1 빌드와 실행

docker build -t myapp:1.0 .
docker run -d -p 8080:8080 myapp:1.0

 

4.2 이미지 크기 비교

docker images myapp

빌드 스테이지만 따로 만들어 크기를 비교할 수도 있어요.

 

docker build --target build -t myapp:build .
docker images

--target 옵션은 지정한 스테이지까지만 빌드해요.

---

5. 알아 두면 좋은 기능

5.1 외부 이미지에서 파일 복사

COPY --from에는 앞 스테이지뿐 아니라 다른 이미지 이름도 쓸 수 있어요.

COPY --from=nginx:latest /etc/nginx/nginx.conf /nginx.conf

 

5.2 앞 스테이지를 이어서 사용

FROM alpine:latest AS builder
RUN apk --no-cache add build-base

FROM builder AS build1
# builder 스테이지 상태에서 이어서 작업

 

5.3 필요한 스테이지만 빌드

공식 문서에 따르면 BuildKit은 목표 스테이지에 필요한 스테이지만 빌드해요. 사용하지 않는 스테이지는 건너뛰어요.

BuildKit: 도커의 이미지 빌드 엔진이에요. 최신 Docker Desktop과 Docker Engine에서 기본으로 사용돼요.

---

6. 핵심 정리

• 멀티 스테이지 빌드는 FROM을 여러 번 써서 빌드와 실행을 나누는 방법이에요.
• 최종 이미지는 마지막 스테이지로만 만들어져요.
• COPY --from으로 필요한 결과물만 옮겨요.
• AS 이름으로 스테이지를 명명하면 유지보수가 쉬워요.
• --target으로 특정 스테이지까지만 빌드할 수 있어요.

---

7. 추가 정보

주의사항

• plain jar 주의: Spring Boot Gradle 플러그인은 ./gradlew build 실행 시 -plain.jar도 함께 만들 수 있어요. 이때 *.jar가 파일 두 개와 일치해 COPY가 실패해요. 예시처럼 bootJar만 실행하거나, build.gradle에서 jar 작업을 끄는 방법이 있어요.
• 베이스 이미지 태그 확인: JRE 전용 이미지가 모든 Java 버전에 제공되는지는 이미지 배포처에서 확인해야 해요.
• 이미지 크기가 얼마나 줄어드는지는 프로젝트마다 달라서, 공식 문서에 확정 수치가 제시되어 있지 않아요.

관련 글

• 도커(Docker) 개념 정리 — 잘못 쓰면 이렇게 됩니다