min8282

스프링 부트 앱, 도커로 빌드하고 EC2에 배포하기 본문

Dev

스프링 부트 앱, 도커로 빌드하고 EC2에 배포하기

min8282 2025. 6. 1. 19:23

 

이번 게시글은 스프링 부트(Spring Boot) 프로젝트를 도커(Docker) 이미지로 만들고, 이를 Docker Hub에 푸시한 다음, EC2 인스턴스에 배포하는 과정을 기록해 두려고 합니다.

1. Spring boot 프로젝트 빌드 및 .jar 파일 생성

먼저, 스프링 부트 프로젝트를 빌드하여 실행 가능한 .jar 파일을 생성해야 합니다. 프로젝트 루트 디렉터리에서 다음 명령어를 실행합니다.

./gradlew clean build

 

성공적으로 실행되면, 프로젝트의 build/lib 디렉토리 안에 [프로젝트 이름].jar와 같은 실행 가능한 JAR 파일이 생성됩니다.

2. Docker 이미지 빌드 및 태그 저장

이제 생성된 JAR 파일을 기반으로 도커 이미지를 만들어 보겠습니다. 도커 이미지는 애플리케이션과 모든 종속성을 포함하는 경량의 독립 실행형 패키지입니다.

2.1. 도커 이미지 빌드

Dockerfile이 있는 프로젝트 루트 디렉토리에서 다음 명령어를 실행하여 도커 이미지를 빌드합니다. 

docker build --platform linux/amd64 -t [프로젝트명]:[태그명] .
  • docker build: 도커 이미지를 빌드하는 명령어
  • --platform linux/amd64: 현재 개발 환경(저는 현재 M1)이 이미지 실행 환경과 다를 경우, 타켓 플랫폼을 명시하여 호환성 문제를 방지
  • -t [프로젝트명]:[태그명]: 빌드된 이미지에 로컬에서 사용할 이름과 태그를 부여합니다. [프로젝트명]은 이미지 이름, [태그명]은 버전 태그
  • . : 현재 디렉토리에서 Dockerfile을 찾아서 빌드하는 의미

2.2. Docker Hub 푸시를 위한 태그 변경 (별칭 부여)

빌드된 이미지를 Docker Hub와 같은 원격 저장소에 푸시하려면, 해당 저장소의 이름 규칙을 따라야 합니다. 일반적으로 [Docker Hub 계정명]/[저장소명]:[테그] 형식입니다.

docker tag [이미지명]:[태그명] min82/[저장소명]:[태그명]
  • docker tag: 기존 이미지에 새로운 이름(별칭)을 부여하는 명령어
  • [이미지명]:[태그명]: 로컬에 존재하는 원본 이미지의 이름과 태그
  • min82/[저장소명]:[태그명]: Docker Hub에 푸시할 때 사용할 새로운 이름
    • min82: 사용할 Docker Hub 계정 이름
    • [저장소명]: Docker Hub에 생성할 저장소 이름
    • [태그명]: 이미지의 버전 태그

이 명령은 실제 이미지를 복사하는 것이 아니라, 앞서 로컬에 만든 [프로젝트명]:[태그명] 이미지에 min82/[저장소명]:[태그명]이라는 새로운 참조(포인터)를 추가하는 것입니다.

2.3. Docker Hub에 이미지 푸시

이제 새롭게 태그된 이미지를 Docker Hub에 업로드(푸시)합니다. 이렇게 하면 EC2와 같은 다른 서버에서 이 이미지를 쉽게 가져와 사용할 수 있습니다.

docker push min82/[저장소명]:[태그명]
  • docker push: 로컬 이미지를 원격 저장소에 업로드하는 명령어
  • min82/[저장소명]:[태그명]: 푸시할 이미지의 원격 저장소 형식 이름. 이 명령을 실행하기 전에 docker login 명령으로 Docker Hub에 로그인되어 있어야 함

3. EC2에서 기존 컨테이너 중지 및 삭제 (업데이트 시)

만약 EC2 인스턴스에 이미 이전 버전의 애플리케이션 컨테이너가 실행 중이라면, 새로운 버전을 배포하기 전에 기존 컨테이너를 중지하고 삭제해야 합니다.

처음 배포하거나 컨테이너가 실행 중이 아님을 확실히 아는 경우에는 이 단계를 건너뛰어도 됩니다.
docker stop [컨테이너명]
docker rm [컨테이너명]
  • docker stop [컨테이너명]: [컨테이너명]라는 이름의 실행 중인 컨테이너를 중지
  • docker rm [컨테이너명]: 중지된 [컨테이너명] 컨테이너를 삭제

4. 새로운 버전 이미지 Pull 및 배포

이제 EC2 인스턴스에서 Docker Hub에 푸시한 최신 버전의 이미지를 가져와 새로운 컨테이너로 배포합니다.

docker pull min82/[저장소명]:[태그명]
  • docker pull: 원격 저장소에서 도커 이미지를 다운로드하는 명령어

이미지 다운로드가 완료되면, 이 이미지를 사용하여 새로운 컨테이너를 실행합니다.

docker run -d -p 8080:8080 --name [사용할 컨테이너명] min82/[저장소명]:[태그명]
  • docker run: 새로운 도커 컨테이너를 생성하고 실행하는 명령어
  • -d: 컨테이너를 백그라운드에서 실행 (detached mode)
  • -p 8080:8080: 호스트(EC2 인스턴스)의 8080번 포트를 컨테이너의 8080번 포트에 연결(포트 포워딩). 이렇게 해야 외부에서 EC2의 8080번 포트로 접근했을 때 컨테이너의 스프링 부트 앱에 연결됨.
  • --name [사용할 컨테이너명]: 컨테이너에 이름을 부여함. 이 이름은 컨테이너를 관리(중지, 삭제 등)할 때 사용됨
  • min828/[저장소명]:[태그명]: 실행할 도커 이미지의 이름과 태그

이제 EC2 인스턴스에서 스프링 부트 애플리케이션이 도커 컨테이너 형태로 성공적으로 실행되고 있을 겁니다. 이 방법은 애플리케이션의 버전 관리를 용이하게 하고, 환경에 구애받지 않는 일관된 배포를 가능하게 합니다. 

다만, 새로운 기능 추가 및 수정할 때마다 해당 과정을 반복해야 합니다. 때문에 이후에는 Github Actions를 사용하여 CI/CD 구축을 진행해볼까 합니다.