[Docker] Docker 이미지 빌드 & 배포

이번 포스트에서는 Docker 이미지 빌드 및 배포 과정에 대해 상세히 알아보겠습니다.

 

Docker 이미지를 효율적으로 빌드하고 배포하는 방법을 이해하면, 개발부터 운영까지의 전 과정을 더욱 원활하게 관리할 수 있습니다.

이 글에서는 docker buildx build 명령어를 중심으로 이미지 빌드와 배포 과정을 구체적으로 설명드리겠습니다.

---

Docker 이미지 빌드 

Docker 이미지는 애플리케이션과 그 실행에 필요한 모든 종속성을 포함하는 불변의 파일 시스템 스냅샷입니다. 이미지를 기반으로 컨테이너를 생성하여 애플리케이션을 실행할 수 있습니다. 이미지를 효율적으로 관리하고 배포하는 것은 애플리케이션의 일관성과 안정성을 보장하는 데 필수적입니다.

Docker Buildx Build 명령어

Docker는 기본적으로 docker build 명령어를 사용하여 이미지를 빌드하지만, docker buildx build는 더 강력한 빌드 기능을 제공합니다. buildx는 멀티 플랫폼 빌드, 캐시 관리, 빌드 비밀 관리 등 다양한 고급 기능을 지원합니다.

---

주요 옵션 설명

docker buildx build 명령어는 여러 가지 옵션을 제공하여 빌드 과정을 세밀하게 제어할 수 있습니다.
주요 옵션과 그 기능을 아래에 상세히 설명드립니다.

1. -t 또는 --tag
   • 설명: 빌드할 이미지의 리포지토리 이름과 태그를 지정합니다.
   • 사용법: -t [리포지토리명]:[태그]
   • 기본값: 지정하지 않으면 기본적으로 latest 태그가 지정됩니다.
   • 주의사항: 태그를 명시하지 않으면 댕글링(dangling) 이미지로 빌드될 수 있으므로, 특별한 경우가 아니면 태그를 명시적으로 지정하는 것이 좋습니다.
2. --build-arg
   • 설명: Dockerfile 내에서 사용할 빌드 인자(Build Arguments)를 전달합니다.
   • 사용법: --build-arg [변수명]=[값]
   • 예시: --build-arg NODE_VERSION=20.15.1
   • 용도: 빌드 과정에서 변수 값을 동적으로 설정할 때 유용합니다.
3. -f 또는 --file
   • 설명: 사용할 Dockerfile의 경로를 지정합니다.
   • 사용법: -f [Dockerfile 경로]
   • 기본값: 지정하지 않으면 빌드 컨텍스트의 최상단에 있는 Dockerfile을 사용합니다.
   • 용도: 여러 Dockerfile이 있는 경우 특정 파일을 지정할 때 사용합니다.
4. --pull
   • 설명: 빌드 시 항상 최신 베이스 이미지를 다운로드합니다.
   • 사용법: --pull
   • 용도: 베이스 이미지가 업데이트된 경우 이를 반영하여 최신 상태로 빌드할 때 유용합니다.
5. 빌드 컨텍스트
   • 설명: 빌드할 파일들이 위치한 디렉토리나 URL을 지정합니다.
   • 사용법: 마지막 인자로 지정하며, 일반적으로 .을 사용하여 현재 디렉토리를 의미합니다.

Docker Buildx Build 명령어 옵션 설명

 

옵션	설명	사용법	예시 및 주의사항
-t 또는 --tag	빌드할 이미지의 리포지토리 이름과 태그를 지정합니다.	-t [리포지토리명]:[태그]	- 예시: -t learncodeit/mbti:embedded-db - 주의사항: 태그를 명시하지 않으면 latest 태그가 자동으로 지정됩니다. 태그를 지정하지 않으면 댕글링(dangling) 이미지로 빌드될 수 있으므로, 특별한 경우가 아니면 명시적으로 지정하는 것이 좋습니다.
--build-arg	Dockerfile 내에서 사용할 빌드 인자(Build Arguments)를 전달합니다.	--build-arg [변수명]=[값]	- 예시: --build-arg NODE_VERSION=20.15.1 - 용도: 빌드 과정에서 변수 값을 동적으로 설정할 때 유용합니다.
-f 또는 --file	사용할 Dockerfile의 경로를 지정합니다.	-f [Dockerfile 경로]	- 예시: -f ./Dockerfile - 기본값: 지정하지 않으면 빌드 컨텍스트의 최상단에 있는 Dockerfile을 사용합니다. - 용도: 여러 Dockerfile이 있는 경우 특정 파일을 지정할 때 사용합니다.
--pull	빌드 시 항상 최신 베이스 이미지를 다운로드합니다.	--pull	- 용도: 베이스 이미지가 업데이트된 경우 이를 반영하여 최신 상태로 이미지를 빌드할 때 유용합니다.
빌드 컨텍스트	빌드할 파일들이 위치한 디렉토리나 URL을 지정합니다.	[빌드 컨텍스트] (일반적으로 .)	- 설명: 마지막 인자로 지정하며, 일반적으로 .을 사용하여 현재 디렉토리를 의미합니다. - 용도: 빌드에 필요한 모든 파일이 위치한 디렉토리를 지정합니다.

---

도커파일 빌드 명령어 예제

아래는 docker buildx build 명령어를 사용하여 이미지를 빌드하는 예제입니다.
각 옵션이 어떤 역할을 하는지 상세히 설명드리겠습니다.

docker buildx build \
  -t daehyunbigbread/mbti:embedded-db \
  -t daehyunbigbread/mbti \
  --build-arg NODE_VERSION=20.15.1 \
  -f ./Dockerfile \
  --pull \
  .

명령어 설명

• -t daehyunbigbread/mbti:embedded-db와 -t daehyunbigbread/mbti:
  • 설명: 빌드된 이미지를 learncodeit/mbti 리포지토리에 embedded-db 태그와 latest 태그로 각각 지정합니다.
  • 효과: 동일한 이미지에 여러 태그를 붙여, 다양한 버전이나 상태를 쉽게 참조할 수 있습니다.
• --build-arg NODE_VERSION=20.15.1:
  • 설명: Dockerfile 내에서 사용할 NODE_VERSION 빌드 인자에 20.15.1 값을 전달합니다.
  • 효과: Dockerfile에서 동적으로 Node.js 버전을 설정할 수 있습니다.
• -f ./Dockerfile:
  • 설명: 현재 디렉토리의 Dockerfile을 사용하여 이미지를 빌드합니다.
  • 효과: 명시적으로 특정 Dockerfile을 지정하여 빌드할 수 있습니다.
• --pull:
  • 설명: 빌드 시 항상 최신 베이스 이미지를 다운로드합니다.
  • 효과: 베이스 이미지가 업데이트된 경우 이를 반영하여 최신 상태로 이미지를 빌드할 수 있습니다.
• .:
  • 설명: 현재 디렉토리를 빌드 컨텍스트로 사용합니다.
  • 효과: 빌드에 필요한 파일들이 현재 디렉토리에 있다고 가정합니다.

---

빌드된 이미지 확인하기

이미지를 성공적으로 빌드한 후, 로컬 환경에서 빌드된 이미지를 확인할 수 있습니다.

이를 통해 빌드가 제대로 되었는지, 예상한 태그가 붙어있는지 검증할 수 있습니다.

도커 이미지 목록 확인

docker image ls

예시 출력

REPOSITORY              TAG           IMAGE ID       CREATED              SIZE
daehyunbigbread/mbti        embedded-db    5dbed223aa10   About a minute ago   1.86GB
daehyunbigbread/mbti        latest         5dbed223aa10   About a minute ago   1.86GB

• REPOSITORY: 이미지가 속한 리포지토리 이름입니다.
• TAG: 이미지의 태그로, 특정 버전이나 상태를 나타냅니다.
• IMAGE ID: 이미지의 고유 식별자입니다.
• CREATED: 이미지가 생성된 시간입니다.
• SIZE: 이미지의 크기입니다.

위 예시에서 daehyunbigbread/mbti:embedded-db와 daehyunbigbread/mbti:latest 두 개의 태그가 동일한 이미지 ID를 가리키고 있음을 확인할 수 있습니다. 이는 동일한 이미지에 여러 태그를 지정한 결과입니다.

---

Docker Hub에 이미지 배포하기

로컬에서 빌드한 이미지를 Docker Hub와 같은 레지스트리에 배포하여, 다른 환경이나 팀원과 공유할 수 있습니다. Docker Hub는 가장 널리 사용되는 Docker 이미지 레지스트리 중 하나로, 이미지를 쉽게 푸시(push)하고 풀(pull)할 수 있습니다.

이미지 푸시 명령어

Docker 이미지를 Docker Hub에 푸시하려면 다음 명령어를 사용합니다.

푸시하기 전에 Docker Hub에 로그인되어 있어야 합니다. 아직 로그인하지 않았다면, 먼저 로그인하세요.

Docker Hub 로그인

docker login

로그인 시 사용자 이름과 비밀번호를 입력하면 인증이 완료됩니다.

이미지 푸시

개별 태그를 푸시하거나, 모든 태그를 한 번에 푸시할 수 있습니다.

개별 태그 푸시

여기서 daehyunbigbread는 제 개인 docker 리포지토리명 입니다. 혹시나 이걸 따라하시는 분들은 여러분껄로 하셔야 합니다.

• 설명: embedded-db 태그와 latest 태그를 가진 이미지를 각각 푸시합니다.
• 효과: 각 태그에 해당하는 이미지가 Docker Hub에 업로드됩니다.

docker image push daehyunbigbread/mbti:embedded-db
docker image push daehyunbigbread/mbti:latest

 

모든 태그 한 번에 푸시

• 설명: daehyunbigbread/mbti 리포지토리에 있는 모든 태그를 한 번에 푸시합니다.
• 효과: daehyunbigbread/mbti 리포지토리에 있는 모든 태그가 Docker Hub에 업로드됩니다.

docker image push -a daehyunbigbread/mbti

---

Docker Hub에서 배포된 이미지 확인

이미지를 성공적으로 푸시한 후, Docker Hub 웹사이트에 접속하여 해당 리포지토리를 확인할 수 있습니다.

Docker Hub Container Image Library | App Containerization

1. Docker Hub 웹사이트 접속
2. Docker Hub에 접속하여 로그인합니다.
3. 리포지토리 확인
   • 태그 목록: 배포한 모든 태그(embedded-db, latest)가 나열됩니다.
   • 이미지 정보: 각 태그에 대한 상세 정보를 확인할 수 있습니다.
4. 프로필 메뉴에서 Repositories를 선택하고, 배포한 daehyunbigbread/mbti 리포지토리를 클릭합니다. 여기서 푸시된 모든 태그와 이미지 정보를 확인할 수 있습니다.

---

Nest.js 서버 이미지 빌드 및 배포

이제 실제로 Nest.js 서버 애플리케이션을 Docker 이미지를 빌드하고 Docker Hub에 배포하는 과정을 한번 알아보겠습니다.

외부 MySQL 데이터베이스와 연동하여 실행되어야 하는 mbti 애플리케이션을 이미지로 만들어 배포합니다.

실습 요건

1. 베이스 이미지: node:20.15.1
2. 이미지 내 소스 코드 경로: /apps/mbti
3. 환경 변수:
   • PORT: 3001
   • DB_HOST: localhost
   • DB_PORT: 3306
   • DB_NAME: db_mbti
   • DB_USERNAME: user_mbti
   • DB_PASSWORD: pw_mbti
4. node_modules 디렉토리는 복사 대상에서 제외하기

---

애플리케이션 소스 코드 다운로드

먼저, 애플리케이션 소스 코드를 다운로드 받아야 합니다. 다음 링크에서 소스 코드를 다운로드할 수 있습니다.

MBTI MySQL.zip

0.10MB

 

다운로드 받은 mbti-mysql.zip 파일을 압축 해제합니다.

unzip mbti-mysql.zip -d mbti-mysql
cd mbti-mysql

Docker 이미지 빌드

이미지를 빌드하기 위해 docker buildx build 명령어를 사용합니다. 아래는 빌드 명령어와 각 옵션의 상세 설명입니다.

docker buildx build \
    -t daehyunbigbread/mbti:mysql \
    -t daehyunbigbread/mbti \
    --pull \
    .

명령어 설명

• -t daehyunbigbread/mbti:mysql:
  • 설명: daehyunbigbread/mbti 리포지토리에 mysql 태그를 붙인 이미지를 빌드합니다.
  • 효과: 특정 기능(mysql 연동)을 나타내는 태그로 이미지를 식별할 수 있습니다.
• -t daehyunbigbread/mbti:
  • 설명: 동일한 이미지에 latest 태그를 붙입니다.
  • 효과: 최신 이미지를 쉽게 참조할 수 있습니다.
• --pull:
  • 설명: 빌드 시 필요한 베이스 이미지를 항상 최신 버전으로 다운로드합니다.
  • 효과: 베이스 이미지의 업데이트를 반영하여 최신 상태로 이미지를 빌드할 수 있습니다.
• .:
  • 설명: 현재 디렉토리를 빌드 컨텍스트로 사용합니다.
  • 효과: Dockerfile과 빌드에 필요한 모든 파일이 현재 디렉토리에 있다고 가정합니다.

빌드 실행 예시

docker buildx build \
    -t daehyunbigbread/mbti:mysql \
    -t daehyunbigbread/mbti \
    --pull \
    .

빌드가 성공적으로 완료되면, 다음과 같은 출력이 나타납니다.

Successfully built 5dbed223aa10
Successfully tagged daehyunbigbread/mbti:mysql
Successfully tagged daehyunbigbread/mbti:latest

빌드된 이미지 확인

빌드가 완료된 이미지를 로컬에서 확인하려면 다음 명령어를 사용합니다.

docker image ls

예시 출력

REPOSITORY              TAG           IMAGE ID       CREATED             SIZE
daehyunbigbread/mbti    mysql         5dbed223aa10   About a minute ago  1.86GB
daehyunbigbread/mbti    latest        5dbed223aa10   About a minute ago  1.86GB

• REPOSITORY: 이미지가 속한 리포지토리 이름입니다.
• TAG: 이미지의 태그로, mysql과 latest 두 가지 태그가 동일한 이미지 ID를 가리키고 있음을 확인할 수 있습니다.
• IMAGE ID: 이미지의 고유 식별자입니다.
• CREATED: 이미지가 생성된 시간입니다.
• SIZE: 이미지의 크기입니다.

---

Docker Hub에 이미지 배포

빌드된 이미지를 Docker Hub에 배포하여, 다른 환경이나 팀원과 공유할 수 있습니다.

이미지 푸시 명령어

docker image push daehyunbigbread/mbti:mysql
docker image push daehyunbigbread/mbti:latest

또는 모든 태그를 한 번에 푸시할 수도 있습니다.

docker image push -a daehyunbigbread/mbti

푸시 과정 설명

• docker image push daehyunbigbread/mbti:mysql:
  • 설명: daehyunbigbread/mbti 리포지토리에 mysql 태그를 가진 이미지를 푸시합니다.
  • 효과: 해당 태그가 붙은 이미지가 Docker Hub에 업로드됩니다.
• docker image push daehyunbigbread/mbti:latest:
  • 설명: 동일한 리포지토리에 latest 태그를 가진 이미지를 푸시합니다.
  • 효과: latest 태그가 붙은 이미지가 Docker Hub에 업로드됩니다.
• docker image push -a daehyunbigbread/mbti:
  • 설명: daehyunbigbread/mbti 리포지토리에 있는 모든 태그를 한 번에 푸시합니다.
  • 효과: mysql과 latest 태그가 동시에 푸시됩니다.

푸시 결과 확인

Docker Hub 웹사이트에 접속하여 해당 리포지토리를 확인하면, 업로드된 이미지를 확인할 수 있습니다.

• 리포지토리 페이지: 배포한 daehyunbigbread/mbti 리포지토리에서 mysql과 latest 태그가 정상적으로 업로드되었는지 확인할 수 있습니다.
• 태그 목록: 각 태그에 대한 이미지 정보와 빌드 시간을 확인할 수 있습니다.

---

추가 팁 및 주의사항

Docker 이미지를 빌드하고 배포할 때 유의해야 할 몇 가지 팁과 주의사항을 소개합니다.

이미지 태그 관리

• 버전 태그 사용: v1.0.0, v1.0.1 등 버전별로 태그를 지정하여 특정 버전을 쉽게 참조할 수 있습니다.
• latest 태그 주의: latest 태그는 항상 최신 이미지를 가리키므로, 배포 환경에서는 명시적인 태그를 사용하는 것이 안전합니다.
• 일관된 태그 전략: 프로젝트마다 일관된 태그 전략을 수립하여 관리의 편의성을 높입니다.

이미지 크기 최적화

이미지의 크기가 클수록 빌드 및 배포 시간이 길어질 수 있습니다. 다음과 같은 방법으로 이미지 크기를 최적화할 수 있습니다.

• 멀티 스테이지 빌드 사용: 빌드에 필요한 도구는 빌드 단계에서만 사용하고, 최종 이미지에는 포함하지 않습니다.

# 빌드 스테이지
FROM node:20.15.1 AS builder
WORKDIR /app
COPY . .
RUN npm ci && npm run build

# 실행 스테이지
FROM node:20.15.1
WORKDIR /app
COPY --from=builder /app . 
ENV PORT=3000
ENTRYPOINT ["npm", "run", "start"]

 

• 불필요한 파일 제외: .dockerignore 파일을 활용하여 불필요한 파일이 이미지에 포함되지 않도록 합니다.
• 경량 베이스 이미지 선택: 가능하다면 Alpine과 같은 경량 베이스 이미지를 선택합니다.

FROM node:20.15.1-alpine

이미지 보안 강화

이미지 내 소프트웨어의 취약점을 관리하고, 신뢰할 수 있는 소스에서 이미지를 가져오는 것이 중요합니다.

• 신뢰할 수 있는 베이스 이미지 사용: 공식 이미지나 검증된 레포지토리에서 베이스 이미지를 선택합니다.
• 최신 패치 적용: 베이스 이미지를 주기적으로 업데이트하여 보안 패치를 적용합니다.
• 취약점 스캐닝: 이미지 내의 취약점을 스캔하는 도구를 사용하여 보안을 강화합니다. 예를 들어, Docker Security Scanning 또는 Clair와 같은 도구를 활용할 수 있습니다.

이미지 레이어 이해하기

Docker 이미지는 여러 개의 레이어로 구성됩니다. 각 레이어는 이전 레이어 위에 쌓이며, 변경된 부분만 업데이트됩니다.

레이어를 효율적으로 관리하면 빌드 시간을 단축하고 저장 공간을 절약할 수 있습니다.

• 명령어 순서 최적화: 자주 변경되지 않는 명령어를 Dockerfile 상단에 배치하여 캐시 효율을 높입니다.

# 자주 변경되지 않는 의존성 설치
RUN npm ci

# 소스 코드 복사
COPY . /app

# 애플리케이션 빌드
RUN npm run build

• RUN 명령어 결합: 여러 개의 RUN 명령어를 하나로 결합하여 레이어 수를 줄입니다.

RUN apt-get update && apt-get install -y \
    package1 \
    package2 \
    && rm -rf /var/lib/apt/lists/*

 

---

Docker 이미지를 빌드하고 배포하는 과정은 애플리케이션의 일관성과 안정성을 보장하는 데 매우 중요합니다. docker buildx build 명령어를 활용하여 이미지를 효율적으로 빌드하고, Docker Hub와 같은 레지스트리에 배포함으로써 팀 내에서 손쉽게 이미지를 공유할 수 있습니다. 또한, 이미지 태그 관리, 크기 최적화, 보안 강화 등의 팁을 통해 더욱 효과적으로 Docker를 활용할 수 있습니다.

 

참고 자료

• Docker 공식 문서: https://docs.docker.com/
• Dockerfile 참조: Dockerfile reference
• Docker Hub: Docker Hub Container Image Library | App Containerization