프론트엔드 개발자를 위한 Docker 입문
이미지와 레이어의 개념부터 멀티스테이지 빌드로 정적 사이트를 서빙하고 docker-compose로 개발 환경을 묶기까지 프론트엔드 관점의 Docker를 정리했습니다.
프론트엔드 개발자를 위한 Docker 입문
개요
“로컬에서는 되는데요?”를 끝내는 가장 확실한 방법 중 하나가 Docker입니다. 프론트엔드 개발자에게 Docker는 배포 서버가 되어 주기도 하고, 백엔드·DB를 묶은 개발 환경이 되어 주기도 합니다. 이번 글에서는 프론트엔드 작업에 필요한 만큼만 Docker를 정리합니다.
이미지와 레이어
Docker 이미지는 읽기 전용 레이어의 쌓임입니다. Dockerfile의 명령어 하나하나가 레이어가 되고, 각 레이어는 캐시됩니다. 다시 빌드할 때 변경된 명령어 이후의 레이어만 다시 만들어지니, 명령어 순서가 빌드 속도를 결정합니다.
FROM node:20-alpine
WORKDIR /app
# 의존성을 먼저 복사하고 설치한다 (소스 변경에도 캐시 유지)
COPY package.json package-lock.json ./
RUN npm ci
# 그다음 소스를 복사한다
COPY . .
RUN npm run build
package.json을 먼저 복사하고 npm ci를 실행하는 이유가 바로 이것입니다. 소스 파일만 바뀌면 의존성 설치 레이어는 캐시를 재사용합니다. 반대로 COPY . .를 먼저 쓰면 코드 한 줄 바꿀 때마다 의존성을 처음부터 다시 받습니다. .dockerignore로 node_modules와 .git을 제외하는 것도 기본입니다.
멀티스테이지 빌드로 정적 사이트 서빙
프론트엔드 빌드 결과물은 결국 정적 파일입니다. 빌드에 Node가 필요하지만 실행에는 필요 없으니, 빌드 단계와 서빙 단계를 나누는 것이 멀티스테이지 빌드입니다.
# 1단계: 빌드
FROM node:20-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
# 2단계: 서빙 (Nginx로 정적 파일 제공)
FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
SPA 라우팅을 쓴다면 모든 경로를 index.html로 보내는 설정이 필요합니다.
server {
listen 80;
location / {
root /usr/share/nginx/html;
index index.html;
try_files $uri $uri/ /index.html;
}
}
이렇게 만든 이미지는 빌드 도구가 전부 빠진 상태라 수십 MB 수준으로 작아집니다. Node 이미지를 통째로 들고 있는 것과 비교하면 pull 속도와 보안 노출면에서 모두 유리합니다.
docker build -t my-blog .
docker run -p 8080:80 my-blog
localhost:8080에서 사이트가 떠 있는 것을 확인할 수 있습니다.
docker-compose로 환경 묶기
프론트엔드 개발에서 Docker의 진짜 가치는 복잡한 로컬 환경을 하나로 묶을 때 나옵니다. 예를 들어 API 서버와 DB가 필요한 프로젝트라면 docker-compose.yml 하나로 정의합니다.
services:
web:
build:
context: .
dockerfile: Dockerfile
ports:
- '8080:80'
depends_on:
- api
api:
image: node:20-alpine
working_dir: /app
volumes:
- ./server:/app
command: npm run dev
ports:
- '3000:3000'
environment:
DATABASE_URL: postgres://dev:dev@db:5432/app
db:
image: postgres:16-alpine
environment:
POSTGRES_USER: dev
POSTGRES_PASSWORD: dev
POSTGRES_DB: app
ports:
- '5432:5432'
volumes:
- db-data:/var/lib/postgresql/data
volumes:
db-data:
docker compose up 한 번으로 프론트, API, DB가 함께 뜹니다. 서비스 이름(api, db)이 컨테이너 네트워크 안의 호스트명이 되므로 환경 변수에서 localhost가 아니라 서비스 이름을 쓰는 점만 주의하면 됩니다. 새로 입사한 동료가 첫날에 개발 환경을 띄우는 데 걸리는 시간이 하루에서 십 분으로 줄어든 게 이 파일의 성과였습니다.
자주 묻는 질문들
HMR(핫 리모드 리로드)이 있는 개발 서버까지 Docker로 돌릴 필요는 있을까요? 저는 보통 개발 서버는 호스트에서 돌리고, DB나 백엔드처럼 버전이 중요한 것만 컨테이너로 띄웁니다. 소스 코드 마운트와 폴링 설정을 잘 해주면 전부 컨테이너에서 돌릴 수도 있지만, macOS에서 파일 시스템 성능 때문에 체감이 느릴 수 있습니다.
마무리
프론트엔드 개발자에게 필요한 Docker는 결국 세 가지입니다. 레이어 캐시를 고려한 Dockerfile, 멀티스테이지로 만든 가벼운 정적 사이트 이미지, 그리고 compose로 묶은 개발 환경. 배포 파이프라인이 어떻게 생겼든 이 기본기를 알고 나면 “인프라팀에게 굽실거리는” 대신 내가 결과물을 끝까지 책임질 수 있게 됩니다.