🚀 React + Vite 프로젝트를 Docker로 배포하는 방법

이 글에서는 React + Vite 프로젝트를 Docker 컨테이너로 패키징하고 실행하는 전체 과정을 다루고자 합니다.

Dockerfile을 활용하여 Node.js로 빌드 후, Nginx를 이용한 정적 파일 서빙 방식을 설명하도록 하겠습니다

또한, 각 명령어의 의미와 수행 이유도 함께 정리하였습니다.

---

✅ 1. 왜 React + Vite를 Docker 컨테이너에서 실행할까?

🔹 Docker를 활용하는 이유

1. 환경 일관성 유지
   • 개발 환경, 테스트 환경, 운영 환경을 동일한 컨테이너 환경에서 실행 가능.
   • "내 로컬에서는 잘 되는데?" 같은 문제 해결.
2. 배포 및 관리 편의성
   • 이미지를 만들어두면 어디서든 실행 가능.
   • Kubernetes, AWS ECS 등과 연계하여 확장 가능.
3. Nginx를 활용한 성능 최적화
   • React는 정적 파일(HTML, CSS, JS)로 제공되므로,Node.js 대신 Nginx를 사용하여 효율적으로 서빙.

---

✅ 2. 프로젝트에 필요한 파일 구조

jungle-gym-ft/
│── src/                # React 프로젝트 소스 코드
│── public/             # 정적 파일
│── package.json        # 프로젝트 의존성 및 스크립트
│── Dockerfile          # Docker 빌드 및 실행 설정
│── .dockerignore       # Docker 빌드 시 제외할 파일 설정

---

✅ 3. Dockerfile 작성 및 분석

📌 Dockerfile

# 1️⃣ Node.js 환경에서 React 빌드
FROM node:18 AS build
WORKDIR /app

# package.json과 package-lock.json을 먼저 복사하여 의존성 설치
COPY package.json package-lock.json ./
RUN npm install

# 전체 소스 코드 복사 후 빌드 실행
COPY . .
RUN npm run build

# 2️⃣ Nginx를 사용하여 정적 파일 서빙
FROM nginx:latest
COPY --from=build /app/dist /usr/share/nginx/html

# 환경 변수 설정
ENV PORT=80
EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

---

📌 Dockerfile 상세 분석

📍 1️⃣ React 프로젝트 빌드 단계 (Build Stage)

FROM node:18 AS build

✅ Node.js 18을 기반으로 컨테이너를 생성

• 최신 React/Vite 프로젝트를 빌드하기 위해 Node.js 18 환경을 사용.

WORKDIR /app

✅ 컨테이너 내부에서 작업할 디렉토리 설정

• /app 디렉토리에서 모든 작업을 수행.

COPY package.json package-lock.json ./
RUN npm install

✅ 패키지 설치 최적화

• package.json, package-lock.json만 먼저 복사하고 npm install을 실행.
• 이후 COPY . .을 실행하는 이유는 변경이 없으면 캐싱하여 빌드 속도 단축.

COPY . .
RUN npm run build

✅ 소스 코드 복사 후 빌드

• npm run build를 실행하여 dist/ 디렉토리에 정적 파일을 생성.

---

📍 2️⃣ Nginx로 정적 파일 서빙 (Runtime Stage)

FROM nginx:latest

✅ Node.js가 아닌 Nginx를 사용하여 정적 파일 서빙

• React는 SSR(Server Side Rendering)이 필요하지 않으므로,Nginx로 최적화된 정적 파일 제공.

COPY --from=build /app/dist /usr/share/nginx/html

✅ 빌드된 정적 파일을 Nginx에 복사

• dist/ 폴더를 /usr/share/nginx/html로 복사하면 Nginx가 자동으로 index.html을 서빙.

ENV PORT=80
EXPOSE 80

✅ 포트 설정

• EXPOSE 80: 컨테이너 내부에서 사용할 포트 지정.
  • React 앱을 실행할 기본 포트로 80 사용.
• ENV PORT=80: 환경 변수 설정 (현재 사용하지 않지만 확장 가능).

CMD ["nginx", "-g", "daemon off;"]

✅ Nginx 실행 명령어

• daemon off; → Nginx가 백그라운드로 실행되지 않도록 설정.

---

✅ 4. .dockerignore 작성

node_modules
dist
.vscode
.git
.env

✅ Docker 빌드 시 불필요한 파일 제외

• node_modules : 이미지에 포함할 필요 없음.
• dist : 로컬 빌드 결과물을 포함하지 않음 (컨테이너에서 다시 빌드하기 때문).
• .git, .vscode : 개발 환경 관련 파일 제외.
• .env : 환경 변수 보호.

---

✅ 5. Docker 빌드 및 실행

1️⃣ Docker 이미지 빌드

docker build -t my-react-app .

✅ 이 명령어의 의미

• t my-react-app : 생성된 Docker 이미지를 my-react-app이라는 이름으로 저장.
• . : 현재 디렉토리에 있는 Dockerfile을 사용하여 빌드.

[실행 결과]

---

2️⃣ 컨테이너 실행

docker run -d -p 9080:80 --name react-container my-react-app

✅ 이 명령어의 의미

• d : 백그라운드 모드에서 실행.
• p 9080:80 : 호스트의 9080 포트를 컨테이너의 80 포트와 매핑.
  • 즉, http://localhost:9080로 접근하면 Nginx가 React 앱을 제공.
• -name react-container : 컨테이너 이름을 react-container로 지정.

[실행 결과]

---

3️⃣ 실행된 컨테이너 확인

docker ps

출력 예시:

CONTAINER ID   IMAGE          COMMAND                   CREATED         STATUS         PORTS                  NAMES
a7dacc832e9e   my-react-app   "/docker-entrypoint.…"   4 seconds ago   Up 3 seconds   0.0.0.0:9080->80/tcp   react-container

✅ 확인해야 할 것

• PORTS 부분에서 0.0.0.0:9080->80/tcp이 보이면 정상적으로 실행됨.

[실행 결과]

---

4️⃣ 웹에서 확인

브라우저에서 아래 주소 입력:

http://localhost:9080

✅ 정상적으로 화면이 뜨면 성공! 🎉

---

✅ 6. 실행된 컨테이너 정리

1️⃣ 컨테이너 중지

docker stop react-container

✅ 실행 중인 컨테이너를 중지.

2️⃣ 컨테이너 삭제

docker rm react-container

✅ 컨테이너를 삭제.

3️⃣ Docker 이미지 삭제

docker rmi my-react-app

✅ 빌드된 Docker 이미지를 삭제.

4️⃣ 모든 불필요한 Docker 데이터 정리

docker system prune -a

✅ 사용하지 않는 모든 컨테이너, 이미지, 볼륨 등을 삭제.

⚠️ 주의: 삭제 후 복구 불가능.

---

✅ 7. 최종 요약

단계	명령어	설명
1. Docker 이미지 빌드	docker build -t my-react-app .	my-react-app이라는 이름으로 Docker 이미지 생성
2. 컨테이너 실행	docker run -d -p 9080:80 --name react-container my-react-app	컨테이너 실행 후 9080 포트에서 React 앱 제공
3. 실행 확인	docker ps	실행 중인 컨테이너 목록 확인
4. 웹에서 테스트	http://localhost:9080	React 앱 정상 동작 확인
5. 컨테이너 중지	docker stop react-container	실행 중인 컨테이너 종료
6. 컨테이너 삭제	docker rm react-container	컨테이너 삭제

✅ 이제 Docker를 이용한 React 배포가 가능해졌습니다! 🚀🔥