Spring Boot JAR 파일 Docker 배포 방법

 

---

☕ Spring Boot JAR 파일을 Docker로 배포하는 방법

---

 

🧭 들어가며

Spring Boot 프로젝트를 빌드하면 보통 하나의 실행 가능한 JAR 파일이 생성됩니다.
이 파일을 바로 서버에서 실행할 수도 있지만, Docker 컨테이너로 패키징하면 다음과 같은 장점이 있습니다:

• 환경에 관계없이 동일한 실행 결과 보장
• 배포 자동화 및 버전 관리 용이
• Podman, Kubernetes 등과 손쉽게 연동 가능

이번 글에서는 Spring Boot JAR 파일을 Docker 이미지로 만들고,
실제로 컨테이너로 배포하는 전 과정을 단계별로 정리합니다.

---

⚙️ 1. 준비사항

항목	설명
OS	MacOS, Linux, Windows 모두 가능
필수 설치	Docker 또는 Podman
빌드 도구	Gradle 또는 Maven
예제 JAR	myapp-0.0.1-SNAPSHOT.jar

👉 (참고) Podman을 사용하는 경우에도 Dockerfile 문법은 동일합니다.
단, 명령어에서 docker 대신 podman을 사용하면 됩니다.

---

🧩 2. JAR 빌드하기

Spring Boot 프로젝트 디렉토리에서 다음 명령을 실행하세요.

✅ Maven 기반

./mvnw clean package

✅ Gradle 기반

./gradlew clean build

빌드 후 build/libs 또는 target 폴더에 JAR 파일이 생성됩니다.

예시:

build/libs/myapp-0.0.1-SNAPSHOT.jar

---

📄 3. Dockerfile 작성

루트 디렉토리에 Dockerfile을 생성합니다.

# 1️⃣ Java 17 기반 이미지 선택
FROM openjdk:17-jdk-slim

# 2️⃣ 컨테이너 내 작업 디렉토리 지정
WORKDIR /app

# 3️⃣ JAR 파일 복사
COPY build/libs/myapp-0.0.1-SNAPSHOT.jar app.jar

# 4️⃣ 컨테이너 실행 명령
ENTRYPOINT ["java", "-jar", "app.jar"]

# (선택) 포트 노출
EXPOSE 8080

설명

• FROM : 기본 베이스 이미지 (Java 런타임 포함)
• COPY : 로컬 빌드된 JAR을 컨테이너 내부로 복사
• ENTRYPOINT : 컨테이너 시작 시 JAR 실행 명령
• EXPOSE : 애플리케이션이 사용하는 포트 명시 (문서적 의미)

---

🧱 4. Docker 이미지 빌드

다음 명령으로 이미지를 생성합니다.

docker build -t myapp:latest .

빌드가 완료되면 다음으로 확인할 수 있습니다.

docker images

출력 예시:

REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
myapp        latest    2fdd1c123abc   2 minutes ago    320MB

---

🚀 5. 컨테이너 실행

이제 실제로 애플리케이션을 실행해 봅시다.

docker run -d -p 8080:8080 --name myapp-container myapp:latest

옵션 설명

• -d : 백그라운드 실행
• -p 8080:8080 : 호스트 8080 → 컨테이너 8080 포트 매핑
• --name myapp-container : 컨테이너 이름 지정

실행 후 확인:

docker ps

출력 예시:

CONTAINER ID   IMAGE          COMMAND               STATUS         PORTS                    NAMES
ab12cd34ef56   myapp:latest   "java -jar app.jar"   Up 10 seconds  0.0.0.0:8080->8080/tcp   myapp-container

브라우저에서 다음 URL을 열어 확인합니다.

http://localhost:8080

---

🔁 6. 컨테이너 관리 명령어

기능	명령어
로그 확인	docker logs -f myapp-container
컨테이너 접속	docker exec -it myapp-container /bin/sh
재시작	docker restart myapp-container
중지	docker stop myapp-container
삭제	docker rm myapp-container

---

🧰 7. Podman 환경에서 실행하기

폐쇄망이나 RedHat 기반 환경에서는 Docker 대신 Podman을 자주 사용합니다.
Podman에서는 아래와 같이 명령어만 변경하면 동일하게 동작합니다.

podman build -t myapp:latest .
podman run -d -p 8080:8080 myapp:latest

Podman은 rootless 환경에서도 잘 동작하기 때문에
보안이 중요한 환경에서는 Docker보다 선호됩니다.

---

🧱 8. 다단계(Multi-stage) 빌드로 이미지 최적화하기

빌드 과정까지 Docker 안에서 수행하면 더 깔끔한 배포가 가능합니다.

# 1️⃣ 빌드 단계
FROM gradle:8.5-jdk17 AS builder
WORKDIR /app
COPY . .
RUN gradle clean build -x test

# 2️⃣ 런타임 단계
FROM openjdk:17-jdk-slim
WORKDIR /app
COPY --from=builder /app/build/libs/*.jar app.jar
ENTRYPOINT ["java", "-jar", "app.jar"]

장점

• 빌드 환경과 런타임 환경을 분리 → 이미지 크기 감소 (약 500MB → 300MB)
• CI/CD 파이프라인에 쉽게 통합 가능

---

☁️ 9. Docker Hub 또는 사내 레지스트리에 푸시하기

이미지를 다른 서버에서도 사용하려면 레지스트리에 업로드합니다.

Docker Hub

docker tag myapp:latest mydockerid/myapp:latest
docker push mydockerid/myapp:latest

사내 레지스트리 (예: 10.0.0.5:5000)

docker tag myapp:latest 10.0.0.5:5000/myapp:latest
docker push 10.0.0.5:5000/myapp:latest

---

🧠 마무리

이제 여러분의 Spring Boot JAR 파일은 완전한 Docker 애플리케이션이 되었습니다.
한 줄 요약하자면:

“Java → JAR → Dockerfile → build → run”
이 5단계면 완벽한 컨테이너 배포가 가능합니다.

다음 단계로는 docker-compose.yml을 활용하여
DB나 Redis와 함께 서비스를 구성하거나,
Podman + systemd를 이용해 자동 기동 환경까지 만들 수 있습니다.

---

📎 예제 전체 코드 요약

myapp/
├── build/libs/myapp-0.0.1-SNAPSHOT.jar
└── Dockerfile

Dockerfile

FROM openjdk:17-jdk-slim
WORKDIR /app
COPY build/libs/myapp-0.0.1-SNAPSHOT.jar app.jar
ENTRYPOINT ["java", "-jar", "app.jar"]
EXPOSE 8080

---

💡 Tip: 실무에서 자주 하는 설정

목적	설정 예시
JVM 메모리 제한	ENTRYPOINT ["java", "-Xmx512m", "-jar", "app.jar"]
환경변수 전달	docker run -e SPRING_PROFILES_ACTIVE=prod ...
로그 출력	docker logs -f <container>

---

👉 요약:

JAR 파일만 있으면 Docker로 손쉽게 배포 가능하다.
Dockerfile만 잘 작성하면 운영 환경 이식성이 극대화된다.