Node.js Docker로 배포하기

 

Mafia Game - 역대글

▶ Node.js Docker로 배포하기

▶ Next.js Docker로 배포하기

▶Github Actions으로 배포 자동화

▶ 첫 번째 토이 프로젝트를 완료하고

 

토이 프로젝트로 마피아 게임을 만들었는데, 클라이언트끼리 통신을 위해서 웹소켓 서버가 필요했다. 

그래서 호다닥 만든 다음 실제로 사용하기 위해서 배포를 진행하려고 한다. 

 

이때 Docker를 사용하는 이유는 하나의 서버에 여러 서비스를 배포할 생각이기 때문이다. 

(이것 저것 배포하는 실험실?)

Linux Ubuntu 24.04 버전을 사용하고 있는 환경에 Docker를 설치까지는 선행으로 진행했고 이어서 배포를 하려고 한다. 

 

Docker File

1. Base Image 선택

FROM node:20.16-alpine3.19 as build

첫 번째 단계는 프로젝트를 실행할 base image를 선택하는 것이다. 애플리케이션이 Node.js를 필요로 하기 때문에 도커 허브에서 공식적으로 지원하는 Node.js image를 사용했다. 

 

여기서는 로컬 환경에 설치한 Node.js 버전(20.16.0)과 동일한 이미지를 선택해 일관성을 유지하였다. 

2. 작업 디렉토리 설정

WORKDIR /build

WORKDIR 명령어를 통해 컨테이너 내부의 작업 디렉토리를 /build로 설정했다. 

 

이 명령어를 사용하면 mkdir과 cd를 사용하지 않아도 디렉토리로 바로 이동할 수 있고 이후 명령어는 해당 디렉토리를 기준으로 실행된다. 

3. 의존성 파일 복사

COPY package.json yarn.lock ./

의존성 설치 전에 package.json과 yarn.lock 파일을 컨테이너에 복사한다. 

이 단계는 Docker의 레이어 캐싱 메커니즘을 활용하는 데 중요하다. 

 

※ 레이어 캐싱

Docker는 레이어 기반으로 실행된다. 여기서 레이어란 COPY, RUN 등 명령어를 실행하면 레이어가 생성되며, 레이어는 변경되지 않으면 캐싱된 결과를 재활용한다. 

 

프로젝트를 진행하면서 의존성 변경과 애플리케이션 코드 변경 중 의존성 변경의 빈도가 더 낮으므로, 앞단에 배치하면 의존성이 변경되기 전까진 캐싱된 레이어를 활용하여 빌드 속도를 높일 수 있다. 

4. 의존성 설치

RUN yarn install

• yarn install : package.json과 yarn.lock 파일에 정의된 프로젝트의 의존성을 설치한다.

5. 애플리케이션 복사

COPY . .

현재 디렉토리의 모든 파일을 컨테이너의 작업 디렉토리(/build)로 복사한다. COPY source destination

• source : Dockerfile이 있는 디렉토리를 말한다. 
• destination : 컨테이너 작업 디렉토리 (WORKDIR에 설정한 디렉토리)

6. 애플리케이션 빌드

RUN yarn build

프로젝트를 빌드하여 배포 준비를 완료한다. 

빌드를 할 때 필요한 devDependencies는 배포할 때는 필요가 없기 때문에 단계를 나눠 Docker image를 최적화 하려고 했다. 

7. 배포 이미지 선택

FROM node:20.16-alpine3.19 as production

6번까지 빌드 과정을 진행했다면 이후에는 배포를 위한 작업을 진행한다. 

이렇게 나눈 이유는 배포 시 devDependencies가 필요 없기 때문에 Docker image에서 제외하기 위해서이다. 

8. 작업 디렉토리 설정 및 의존성 파일 복사

WORKDIR /app
COPY package.json yarn.lock ./

9. 패키지 설치 및 캐시 초기화 

RUN yarn install --production

• --production : devDependencies는 필요 없기 때문에 제외하는 작업을 진행했다. 

10. 빌드 파일 복사

COPY --from=build /build/dist ./dist

build 단계에서 빌드한 결과물을 현재 작업 디렉토리로 복사해온다. 

from의 build는 1단계의 as build의 build이다. 

11. 배포 포트 설정

EXPOSE 4000

배포 시 사용할 포트를 지정한다. 

Docker 컨테이너가 내부의 애플리케이션이 사용하는 포트를 명시적으로 선언하는 역할을 한다. 

12. 실행 

CMD ["node", "dist/app.js"]

마지막으로 실행 명령어를 통해서 실행할 수 있게 된다. 

 

FROM node:20.16-alpine3.19 as build

# 작업 디렉토리 변경
WORKDIR /build

# 패키지 파일 build 디렉토리에 복사
COPY package.json yarn.lock ./

# 패키지 설치 및 캐시 초기화 
# npm이라면 RUN npm ci --omit=dev && npm cache clean --force
RUN yarn install && yarn cache clean

COPY . .

RUN yarn build

# 빌드 파일을 복사
FROM node:20.16-alpine3.19 as production

WORKDIR /app

# 패키지 파일 복사
COPY package.json yarn.lock ./

# 패키지 설치 및 캐시 초기화
RUN yarn install --production && yarn cache clean

# 빌드 파일 복사
COPY --from=build /build/dist ./dist

# 빌드 포트 설정
EXPOSE 4000

# 실행 명령어
CMD ["node", "dist/app.js"]

종합하면 위와 같은 코드로 구성할 수 있다. 

여기까지 Docker 설정을 끝냈다면 이미지를 빌드하고 실행하는 단계가 남아있다. 

 

Docker 배포

docker build . -t [name]

Docker image 파일을 만드는 명령어로 [name]이라는 명칭으로 현재 디렉토리를 빌드 컨텍스트로 지정해서 이미지 파일을 만든다는 것이다. 

• docker build : 
  
  • Docker 이미지 생성 명령어 
• . 
  • 현재 디렉토리를 빌드 컨텍스트로 지정한다. 
  • Dockerfile 및 빌드에 필요한 파일이 해당 디렉토리에 있어야 한다. 
• -t [name]
  • 생성된 이미지에 태그를 붙인다. 
  • [name]은 이미지 이름으로 버전과 함께 사용할 수 있다. 

 

docker run --rm --name [실행명칭] -d --env-file .env.production --publish 4000:4000 [이미지파일]

• --rm (remove)
  • 컨테이너가 중지되면 자동으로 삭제한다. 
  • 디스크에 불필요한 중단된 컨테이너가 남지 않게 정리할 때 사용한다. 
• --name [실행명칭]
  • 컨테이너에 명칭을 부여한다. 
  • 나중에 컨테이너를 관리할 때 이름으로 접근할 수 있다. 
• -d
  • 컨테이너를 백그라운드에서 실행한다. 
  • 실행 후 터미널을 점유하지 않고, 다른 작업을 진행할 수 있다. 
• --env-file .env.production
  • 환경 변수 파일을 컨테이너에 전달한다. 
  • 컨테이너 내부에서 process.env로 읽을 수 있게 설정한다. 
• --publish 4000:4000
  • 호스트와 컨테이너 간의 포트를 매핑한다. 
  • [호스트포트]:[컨테이너포트]
• [이미지 파일]
  • 실행할 이미지 이름 또는 태그를 지정한다.

이 과정을 통해서 Node.js 파일을 서버를 통해 배포하는 방법을 알아봤다.