도커를 활용한 프론트엔드 개발 환경 구축: Vite + React

1. 개발환경 구축의 차이점

1) 전통적인 개발 환경 구축

도커 같은 컨테이너 기술이 널리 알려지기 전에는 개발자별로 로컬 환경 설정을 해야했습니다. 온 보딩 문서를 보면서 개발자 PC(로컬 환경)에 Node.js, npm 등 필요한 라이브러리 등을 직접 설치하고, 개발 환경을 수동으로 셋팅한 후에 개발을 시작할 수 있었습니다. 개발 인원이 적고, 단 시간 내에 빠르게 개발을 시작하는 프로젝트라면 전통적인 개발 환경을 구축하여 개발할 수 있습니다.

2) 도커를 활용한 개발 환경 구축

도커를 사용하여 개발 환경을 구축하게 되면 모든 개발자가 동일한 컨테이너 이미지를 사용하므로 버전 불일치나 환경 구성 차이로 인한 오류를 줄일 수 있습니다. 또한 새롭게 합류한 팀원이 있더라도, 레포지토리 clone 후 docker compose up 또는 docker run 명령어로 필요한 개발환경을 구성할 수 있습니다.

2. 도커란 무엇인가?

Docker는 애플리케이션을 실행하는 데 필요한 모든 파일과 설정을 하나의 컨테이너로 묶어주는 플랫폼입니다. 컨테이너는 가상 머신과는 다르게 호스트 운영 체제의 커널을 공유하므로, 가볍고 빠르게 실행됩니다. 컨테이너는 애플리케이션과 라이브러리, 설정 파일을 함께 포함한 독립적인 실행 환경을 제공합니다. 이를 통해 개발자가 동일한 환경에서 작업할 수 있어, 로컬 개발 환경과 배포 환경 간의 불일치를 줄일 수 있습니다. 컨테이너는 특정 작업만을 위해 필요한 최소한의 환경만 포함하기 때문에 효율적입니다.

3. 도커 기반 개발환경 구축

1) Docker 설치

Docker 공식 사이트에서 OS에 맞는 버전을 다운로드하여 설치

2) 설치 후 Docker가 제대로 실행되는지 확인합니다.

docker --version
Docker version 27.4.0, build bde2b89

3) vite react app 설치

npm create vite@latest my-react-app --template react
cd my-react-app
npm install

npm run dev

npm run dev 또는 yarn dev 를 실행하면 아래 이미지와 같이
브라우저에서 localhost:5173 으로 이동하면 vite+react app 기본화면이 실행됩니다.

4) Dockerfile 만들기

Dockerfile 이란 도커 이미지를 생성하기 위한 설정 파일입니다. 각 명령어는 이미지 빌드 과정에서 실행되어 컨테이너의 실행 환경을 구성합니다.
my-react-app 프로젝트의 root 하위에 Dockerfile.dev 파일을 생성합니다.
생성된 파일 내부에 다음과 같이 내용을 작성합니다.

• Dockerfile.dev

FROM node:22

WORKDIR '/app'

COPY package*.json ./

RUN npm install && npm cache clean --force

COPY . .

CMD ["npm", "run", "dev"]

FROM node:22
Node.js 22 버전의 공식 베이스 이미지를 사용합니다. 이 이미지는 Node.js와 NPM(Node Package Manager)을 포함하며, 애플리케이션 실행을 위한 환경을 제공합니다.

WORKDIR '/app'
컨테이너 내에서 작업 디렉토리를 /app으로 설정합니다. 이후 실행되는 모든 명령어는 이 디렉토리를 기준으로 실행됩니다.

COPY package*.json ./
로컬 시스템의 package.json 및 package-lock.json 파일을 컨테이너의 현재 작업 디렉토리(WORKDIR로 설정된 /app)로 복사합니다. 의존성 설치를 위해 사용됩니다.

RUN npm install && npm cache clean --force

NPM을 사용하여 package.json에 정의된 프로젝트 의존성을 설치합니다. 이후 npm cache clean --force를 통해 NPM 캐시를 정리하여 이미지 크기를 줄이고 불필요한 파일을 제거합니다.

COPY . .

현재 디렉토리의 모든 파일과 폴더를 컨테이너의 작업 디렉토리(/app)로 복사합니다. 이 명령어는 소스 코드와 기타 파일을 컨테이너로 가져옵니다.

CMD ["npm", "run", "dev"]

컨테이너가 실행될 때 기본적으로 실행되는 명령어를 정의합니다. 여기서는 NPM 스크립트 dev를 실행하여 Vite 개발 서버를 시작합니다. 이 서버는 vite.config.js 설정에 따라 애플리케이션을 실행합니다.

5) 도커 이미지 생성.

이제 도커를 사용하여 vite+react app 을 사용할 수 있게 되었습니다.
먼저 docker image 를 만들어야 합니다.

docker build -t docker/vite-react-app -f Dockerfile.dev ./

-t docker/vite-react-app
-t 옵션은 tag 의 약자입니다. 생성하려고 하는 도커 이미지에 docker/vite-react-app 이라는 이름을 붙일 수 있습니다.

-f Dockerfile.dev
-f 옵션은 참조할 도커 파일의 경로를 지정할 수 있습니다. -f 옵션을 붙이지 않으면 기본적으로 `Dockerfile 이라는 파일을 참조하지만 Dockerfile.dev 라고 하는 파일을 참조하도록 설정하였습니다.

./
현재 디렉토리를 빌드 컨텍스트로 가리킵니다. . 을 사용해도 됩니다.

그러면 터미널에서 도커 이미지를 빌드하는 명령어를 실행해 봅시다. 그러면 다음과 같은 응답이 출력됩니다.

도커 이미지 확인

터미널에서 도커 이미지가 잘 만들어졌는지 확인합니다.

docker images

6) 도커 이미지 실행

docker run docker/vite-react-app 

위와 같이 도커 이미지를 실행하여 도커 컨테이너가 시작됩니다.
그리고 브라우저의 url 에 localhost:5173 으로 이동합니다.
그런데 이상합니다. vite+react 기본화면이 출력되지 않고, "사이트에 연결할 수 없음" 이라고 표시될 것입니다.
터미널을 한번 살펴보시기 바랍니다. 그러면 다음과 같이 출력되어 있을 것입니다.

Vite는 네트워크 인터페이스를 통해 외부 장치(예: 같은 네트워크에 연결된 다른 컴퓨터 또는 모바일 디바이스)에서 서버에 접근하도록 허용하지 않습니다.

7) package.json script 설정

package.json

//중략
"scripts": {
    "dev": "vite --host --port 4000",
    //중략
},

--host 옵션의 역할
--host 옵션을 추가하면 Vite가 모든 네트워크 인터페이스에서 요청을 수신하도록 설정됩니다. 여기에 --port 4000 을 추가하여, 네트워크 인터페이스의 요청 포트를 4000 으로 설정하였습니다.
package.json 이 수정되었으면 도커 이미지를 다시 빌드합니다.

 docker build -t docker/vite-react-app -f Dockerfile.dev .

도커 이미지 실행

docker run -p 3000:4000 docker/vite-react-app

-p 옵션

좀전의 이미지 실행 명령어에서 -p 옵션을 추가하였습니다.
호스트 컨테이너와 컨테이너의 포트를 매핑하는 옵션입니다.
3000은 호스트 포트입니다. 즉, 사용자의 로컬 컴퓨터에서 접근할 포트 번호입니다.
4000은 도커 컨테이너 내부에서 실행 중인 어플리케이션이 사용하는 포트로써 package.json 에 설정해 놓은 4000번 포트입니다.

그러면 다음과 같은 응답이 터미널에 출력됩니다.

이제 브라우저에 localhost:3000 을 입력합니다.
그러면 처음 리액트를 실행시켰을 때의 화면이 출력됩니다.

8) 아직 개발은 불편하다.

그런데 이러한 방법으로 개발을 지속하기에는 불편한 점이 많습니다. 왜냐하면 소스코드를 변경하고 변경이 잘되었는지 확인하려면 도커 이미지를 다시 빌드한 뒤에 컨테이너를 생성해야 하기 때문입니다.

먼저 터미널에서 실행 중인 컨테이너를 중지합니다.
docker ps 명령어를 사용하여 실행중인 도커 컨테이너 아이디를 획득하여 컨테이너를 중지합니다.

docker stop 'CONTAINER ID'

도커의 볼륨 마운트 기능을 사용해 보겠습니다.

docker run -d -p 3000:4000 -v /app/node_modules -v $(pwd):/app  docker/vite-react-app

-v 옵션 : 볼륨 마운트

-v 옵션은 호스트 머신의 디렉토리와 도커 컨테이너의 내부 디렉토리를 연결(마운트)합니다. 이 연결은 실시간 동기화되어, 호스트의 소스코드를 변경하면 도커 컨테이너 내부의 해당 디렉토리에도 즉시 반영됩니다. 컨테이너 내부에서 실행되고 있는 vite 는 HMR 기능을 지원하여 소스 코드의 변경사항을 감지하고 브라우저에 반영하게 됩니다.

-v 옵션을 사용하지 않으면

-v 옵션을 사용하지 않고 컨테이너를 실행하면, 도커 이미지에 포함된 소스 코드를 사용합니다. 이 경우에 호스트에서 소스 코드를 수정해도 컨테이너 내부에 반영되지 않게 됩니다.

소스 코드 변경

App.tsx 파일을 변경하고, 소스코드를 저장합니다.
도커 이미지를 다시 빌드하는 과정이 없지만, 브라우저에 바로 반영되는 걸 확인해 볼 수 있습니다.

9) docker compose 사용하기

docker compose 란?

도커 컴포즈(Docker Compose)란, 여러 컨테이너로 구성된 애플리케이션을 쉽고 일관성 있게 설정하고 실행할 수 있도록 해주는 도커의 오픈소스 도구입니다. 일반적으로 도커를 사용하다 보면, 애플리케이션을 여러 개의 컨테이너(예: 웹 서버, DB 서버, 캐시 서버 등)로 나누어 관리하게 되는데, 이때 각 컨테이너를 일일이 실행·종료·연결하기가 번거롭습니다. 도커 컴포즈는 이러한 복잡한 과정을 간소화하여, 하나의 docker-compose.yml 파일에 컨테이너 설정을 정의하고 docker-compose up 명령 한 번으로 모든 컨테이너를 구동할 수 있게 해 줍니다.

디렉토리의 루트 하위에 docker-compose-dev.yml 파일을 생성합니다.

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile.dev
    ports:
      - "3000:4000"
    volumes:
      - /app/node_modules
      - .:/app
    stdin_open: true

터미널에서 다음과 같이 명령어를 입력합니다.

 docker compose -f docker-compose-dev.yml up -d --build 

-f
기본적으로 docker-compose.yml 파일을 사용하는 대신, 특정 Compose 파일(여기서는 docker-compose-dev.yml)을 사용하겠다는 의미입니다.

up
정의된 서비스(컨테이너)들을 실행합니다.
네트워크와 볼륨을 생성하고, 필요한 이미지가 없으면 자동으로 이미지도 풀(Pull)해옵니다.

-d (detached mode)
컨테이너들을 백그라운드에서 실행합니다.
이 옵션이 없으면 터미널에 로그가 실시간으로 출력되어, 다른 작업을 위해 터미널을 사용할 수 없게 됩니다.

--build
컨테이너를 실행하기 전에 이미지를 빌드(또는 리빌드) 하도록 지시합니다.
Dockerfile이 변경되었거나, 새로운 종속성(라이브러리 등)이 추가되었다면 이 옵션을 통해 항상 최신 상태로 이미지를 빌드한 뒤 컨테이너를 띄울 수 있습니다.