Docker 기반 풀스택 구성: MongoDB·Node·React로 만드는 서비스 아키텍처

프론트엔드·백엔드·DB를 하나의 개발·운영 환경으로 통합하는 것이 도커의 강점이다. 이 글은 MongoDB + Node.js API + React SPA를 컨테이너 기반으로 구성하는 전체 흐름을 실무 기준으로 정리한다. “컨테이너 단위로 서비스가 분리되고 네트워크로 연결된다”는 관점이 핵심이다.

---

1. 전체 아키텍처 개요

도커 기반 풀스택 구조는 크게 세 레이어로 나뉜다.

• MongoDB 컨테이너 → 지속적 데이터 저장(Volume 필요)
• Node.js API 컨테이너 → 백엔드 API 서버
• React SPA 컨테이너 → 정적 파일 제공 또는 개발환경(HMR) 실행

컨테이너들은 네트워크로 연결되고, 데이터는 볼륨으로 유지하며, 코드 변경은 개발 환경에서 바인드 마운트로 반영한다.

---

2. MongoDB 컨테이너 구성

데이터 영속화가 우선이다.

볼륨 생성 및 실행

docker volume create mongo-data

docker run -d \
  --name db \
  --network backend \
  -v mongo-data:/data/db \
  -p 27017:27017 \
  mongo:6

포인트:

• backend 네트워크로 다른 서비스와 연결
• mongo-data 볼륨으로 컨테이너 재생성과 무관하게 데이터 유지
• API 서버는 mongodb://db:27017 주소로 접근

---

3. Node.js API 서버 도커화

Dockerfile

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install --production
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

실행

docker build -t api-server .
docker run -d \
  --name api \
  --network backend \
  -e MONGO_URL=mongodb://db:27017 \
  -p 3000:3000 \
  api-server

구조적 의미:

• MongoDB와 동일 네트워크에 있어 이름 기반 DNS 접근 가능
• 운영 환경에서는 볼륨 불필요(데이터는 DB 컨테이너가 담당)
• 환경변수로 DB 주소 분리

---

4. React SPA 도커화 방식 두 가지

React는 개발 환경(dev server) 과 운영 환경(static build) 이 완전히 다르다.

① 개발 환경: 바인드 마운트 + HMR

docker run -d \
  --name frontend \
  --network backend \
  -p 5173:5173 \
  -v $(pwd):/app \
  node:18-alpine \
  sh -c "cd /app && npm install && npm run dev"

특징:

• 코드 변경 즉시 반영
• 개발 시에는 이미지 빌드보다 Bind Mount가 효율적
• API 서버와 네트워크로 연결되므로 CORS 최소화

② 운영 환경: Nginx + 정적 파일 제공

Dockerfile

FROM node:18-alpine AS build
WORKDIR /app
COPY . .
RUN npm install && npm run build

FROM nginx:stable-alpine
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 80

실행:

docker build -t frontend-prod .
docker run -d -p 80:80 --name frontend frontend-prod

의미:

• Multi-stage build로 이미지 최소화
• 운영 환경에서는 정적 파일만 제공

---

5. 서비스 연결: 네트워크 기반 통신 구조

전체 컨테이너는 동일 네트워크에 있어야 한다.

docker network create backend

이후 모든 컨테이너 실행 시 --network backend 지정.

Node → MongoDB

mongodb://db:27017

React → Node API

fetch("http://api:3000/todos")

DNS 기반 이름 해석이므로 IP 변경과 무관하게 안정적으로 연결된다.

---

6. 도커 기반 풀스택 개발의 실무 패턴

• DB는 Named Volume
• API 서버는 이미지 빌드 + 환경변수 기반 설정
• 프론트엔드는 개발 시 Bind Mount, 운영 시 정적 빌드 이미지
• 모든 서비스는 하나의 네트워크에 연결
• 포트 매핑은 “호스트 ↔ 외부 접근용”이며 컨테이너 간에는 필요 없음

---

7. 간단한 전체 실행 예시(Compose 없이)

docker network create backend
docker volume create mongo-data

docker run -d --name db \
  --network backend \
  -v mongo-data:/data/db \
  mongo:6

docker run -d --name api \
  --network backend \
  -e MONGO_URL=mongodb://db:27017 \
  -p 3000:3000 \
  api-server

docker run -d --name frontend \
  --network backend \
  -p 80:80 \
  frontend-prod

Compose는 D7에서 별도로 정리한다.

---

요약 체크리스트

• MongoDB는 볼륨 기반으로 데이터 지속성 확보
• API 서버는 이미지 기반 + 환경변수 설정
• React는 개발/운영 방식이 다르므로 별도 전략 필요
• 동일 네트워크에서 DNS 이름으로 통신
• 운영과 개발 환경을 분리해 관리 단순화