이번 글에서는 NestJS 마이크로서비스를 Docker Hub에 업로드하기 위해 이미지를 생성하고 빌드 및 푸시(push)하는 과정을 단계별로 살펴본다.

이 글은 단순한 명령어 나열이 아니라, 실제 실무 환경에서 코드를 컨테이너 이미지로 만들어 어디서든 실행 가능한 형태로 배포하는 방법을 체계적으로 안내한다.

1️⃣ Docker Hub란?

Docker Hub는 개발자가 만든 이미지를 저장하고 전 세계에 배포할 수 있는 공식 이미지 저장소이다.

GitHub가 소스 코드를 관리한다면, Docker Hub는 실행 가능한 애플리케이션의 형태(이미지) 를 관리하는 공간이라 할 수 있다.

NestJS로 만든 마이크로서비스를 컨테이너로 묶은 뒤, 그 이미지를 Docker Hub에 업로드하면 다른 환경에서도 docker pull 명령어 한 줄로 손쉽게 실행할 수 있다.

2️⃣ Docker Hub 계정 생성

1. https://hub.docker.com 에 접속해 계정을 생성한다.

2. 로그인 후, 오른쪽 상단의 Repositories 메뉴를 선택한다.

3. 새로운 저장소(Repository)를 생성한다.

   • 예: nestjs-microservice

   • Public / Private 설정은 자유롭게 선택하되, 처음에는 Public이 편리하다.

이 저장소가 앞으로 Docker 이미지를 저장할 공간이 된다.

3️⃣ Dockerfile 준비

프로젝트 루트에 다음과 같은 Dockerfile을 준비한다.

# 1. Node.js 베이스 이미지 선택
FROM node:20-alpine

# 2. 앱 디렉토리 생성
WORKDIR /app

# 3. package.json, lock 파일 복사
COPY package*.json ./

# 4. 의존성 설치
RUN npm install --production

# 5. 소스 코드 복사
COPY . .

# 6. NestJS 빌드
RUN npm run build

# 7. 앱 실행
CMD ["node", "dist/main.js"]

이 Dockerfile은 NestJS 앱을 컨테이너 이미지로 빌드하기 위한 최소 구성이다.

4️⃣ Docker 이미지 빌드

프로젝트 루트에서 다음 명령어를 실행한다.

docker build -t <Docker Hub 사용자명>/<저장소명>:<태그> .

예시:

docker build -t hongcoding/nest-micro:v1 .

명령어 구성:

• -t : 태그 지정 옵션

• <Docker Hub 사용자명>/<저장소명>:<태그> : 이미지 이름 규칙

• . : 현재 디렉토리(=Dockerfile 위치)

빌드가 완료되면 아래 명령어로 확인할 수 있다.

docker images

출력 예시:

REPOSITORY               TAG       IMAGE ID       CREATED         SIZE
hongcoding/nest-micro    v1        3ac54b91a0f1   2 minutes ago   180MB

5️⃣ Docker Hub 로그인

Docker Hub에 이미지를 푸시하기 전에 먼저 로그인한다.

docker login

명령어 실행 후 사용자명과 비밀번호를 입력하면 인증이 완료된다.

???? Tip: 2단계 인증(2FA)을 사용하는 경우, 비밀번호 대신 Access Token을 입력해야 한다.

6️⃣ 이미지 푸시(Push)

이미지를 Docker Hub에 업로드한다.

docker push <Docker Hub 사용자명>/<저장소명>:<태그>

예시:

docker push hongcoding/nest-micro:v1

잠시 후 Docker Hub 웹사이트에서 업로드된 이미지를 확인할 수 있다.

docker buildx build --platform linux/amd64,linux/arm64 -t test/fc-nestjs-gateway -f ./apps/gateway/Dockerfile --target production .

7️⃣ 빌드 관련 실무 팁 ????

(1) .dockerignore 파일 추가

빌드 속도 향상 및 보안을 위해 불필요한 파일을 이미지에서 제외한다.

node_modules
.git
Dockerfile
dist
.env

node_modules나 .git 기록, 환경 변수 파일 등이 이미지에 포함되지 않도록 한다.

(2) 환경별 태그 관리

개발(dev) 환경과 운영(prod) 환경을 구분하여 관리하면 편리하다.

docker build -t hongcoding/nest-micro:dev .
docker build -t hongcoding/nest-micro:prod .

(3) 최신 버전 태그 지정

사용자가 별도 버전 명시 없이 최신 버전을 받을 수 있도록 latest 태그를 함께 등록한다.

docker build -t hongcoding/nest-micro:latest .
docker push hongcoding/nest-micro:latest

✅ 마무리

지금까지의 순서를 요약하면 다음과 같다:

1. Docker Hub 계정 및 저장소 생성

2. Dockerfile 작성 및 이미지 빌드

3. docker login으로 인증

4. docker push로 업로드

5.  

이제 이 이미지는 전 세계 어디서든 실행할 수 있는 형태로 배포되었다.

핵심 문장:
코드는 로컬에 머무르지만, Docker 이미지는 전 세계로 퍼진다.