Docker로 Node.js와 MongoDB 연결하는 법 (초보자도 가능한 실습 가이드)

이 글은 Node.js 앱을 Docker로 감싸고, 필요 없는 파일을 정리한 뒤, 컨테이너를 만들어 실행하고 로컬 MongoDB에 연결하는 방법을 설명합니다. 실무에서 자주 쓰이는 실용적인 팁도 함께 소개합니다.

 

---

 

1. Dockerize가 왜 필요할까?

내 컴퓨터에선 잘 되는데, 배포 후 오류가 나는 경우가 종종 있습니다. Docker를 사용하면 실행 환경을 통일할 수 있어 이런 문제를 줄일 수 있습니다.

Docker는 코드, 라이브러리, 설정을 하나의 묶음으로 만들어 어디서나 동일하게 동작할 수 있도록 도와줍니다. Node.js 앱과 MongoDB를 함께 다룰 때 매우 유용합니다.

 

---

 

2. 준비물 확인

 

2. 준비물 확인

• Node.js (v18 이상)
• Docker Desktop (실행 상태여야 함)
• MongoDB (로컬 설치 필요)
• Postman 또는 curl
• 터미널 명령어에 익숙하면 좋습니다

 

---

 

3. 프로젝트 폴더 정리하기

 

3. 프로젝트 폴더 정리하기

Docker를 사용하기 전, 필요 없는 파일을 삭제해 주세요.

CTRL + C
rm -rf node_modules package-lock.json

 

node_modules는 Docker 컨테이너 내부에서 다시 설치되기 때문에 삭제해도 괜찮습니다.

 

---

 

4. Dockerfile 간단히 설명하기

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

이 Dockerfile은 Node.js 앱을 실행하기 위한 기본적인 설정입니다.

 

---

 

5. 이미지 만들기

docker build -t favorites-node:latest .

• -t: 이미지 이름과 태그 지정
• .: 현재 디렉터리 기준

실제 서비스에서는 :v1.0.0 같이 버전 태그를 사용하는 게 좋습니다.

 

---

 

6. 컨테이너 실행하기

docker run \
  --name favorites \
  -d --rm \
  -p 3000:3000 \
  favorites-node:latest

• --name: 컨테이너 이름 설정
• -d: 백그라운드 실행
• --rm: 종료 시 자동 삭제
• -p: 포트 연결 (호스트:컨테이너)

 

docker ps

 

컨테이너가 Up 상태면 정상입니다.

 

---

 

7. 외부 API 연결 테스트

컨테이너 안에서도 인터넷 연결이 가능합니다.

curl http://localhost:3000/movies

응답이 오면 인터넷 연결은 문제 없습니다.

 

---

 

8. 로컬 MongoDB 연결 오류 해결

mongoose.connect('mongodb://localhost:27017/favorites');

위 코드는 컨테이너 내부에서 로컬 MongoDB에 접근하지 못해 실패합니다. 컨테이너 안의 localhost는 컨테이너 자신을 의미합니다.

 

---

 

9. host.docker.internal 사용하기

 

9. host.docker.internal 사용하기

mongoose.connect('mongodb://host.docker.internal:27017/favorites');

 

이 주소는 Docker에서 호스트 PC를 가리킵니다. MongoDB가 호스트에서 실행 중이면 이 방법으로 접근 가능합니다.

docker build -t favorites-node:latest .
docker run --name favorites -d --rm -p 3000:3000 favorites-node:latest

 

---

 

10. 연결 성공 확인

curl http://localhost:3000/favorites

데이터가 응답되면 연결이 잘 된 것입니다.

 

---

 

11. 오류 해결 팁

현상 원인 해결 방법

연결 오류	잘못된 주소	host.docker.internal 확인
실행 후 종료	DB 접근 실패	URI 수정 또는 재시도 로직 필요
포트 충돌	이미 사용 중	다른 포트 번호 사용
인증 오류	MongoDB 꺼짐 또는 인증 필요	MongoDB 실행 또는 인증 정보 추가

 

---

 

12. 자주 묻는 질문

Q1. 코드 변경 시 컨테이너를 매번 다시 실행해야 하나요?
A1. -v $(pwd):/app 옵션으로 live reload가 가능합니다.

Q2. MongoDB도 Docker로 실행하는 게 좋을까요?
A2. 네, 실무에서는 보통 그렇게 구성합니다.

Q3. Windows에서 host.docker.internal이 작동하지 않아요.
A3. Docker를 최신 버전으로 업데이트하거나 IP 주소를 직접 사용해 보세요.

Q4. volume 설정이 꼭 필요할까요?
A4. 데이터 저장이 없다면 꼭 필요하지는 않습니다.

 

---

 

13. MongoDB도 Docker로 옮기기

docker run -d --name mongo -p 27017:27017 mongo:7

이후 URI는 mongodb://mongo:27017/favorites로 설정하고, Docker Compose로 연결합니다.

참고 키워드:

• docker compose node mongo example
• persist mongodb volume docker
• node express docker best practice

 

---

 

14. 핵심 요약

1. 기존 node_modules는 삭제
2. docker build 명령어로 이미지 생성
3. 외부 API는 추가 설정 없이 사용 가능
4. 로컬 DB 접근은 host.docker.internal 사용
5. 소스 코드 변경 시 이미지 재생성
6. Docker Compose를 활용해 멀티 컨테이너 환경 구성

 

---

 

15. 간단 정리

dockerize node application connect local mongodb

1. 기존 서버 정지 및 의존성 폴더 삭제
2. Dockerfile 생성
3. docker build로 이미지 만들기
4. docker run으로 컨테이너 실행
5. MongoDB 연결 주소는 host.docker.internal 사용
6. 연결 확인 후 개발 시작