Dockerfile 작성하기

Dockerfile은 컨테이너 이미지를 만드는 데 사용하는 텍스트 기반 문서예요. 실행할 명령, 복사할 파일, 시작 명령 등에 대한 지시를 이미지 빌더에게 제공해요. 이 가이드를 통해 기본부터 직접 Dockerfile을 작성해 봐요.

출처: 문서

본문

설명

Dockerfile은 컨테이너 이미지를 만드는 데 사용되는 텍스트 기반 문서예요. 이미지 빌더에게 실행할 명령, 복사할 파일, 시작 명령 등을 지시해 줘요.

예를 들어 다음 Dockerfile은 바로 실행 가능한 Python 애플리케이션을 만들어요.

FROM python:3.13
WORKDIR /usr/local/app

# Install the application dependencies
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

# Copy in the source code
COPY src ./src
EXPOSE 8080

# Setup an app user so the container doesn't run as the root user
RUN useradd app
USER app

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080"]

주요 지시문

Dockerfile에서 가장 흔히 쓰이는 지시문 몇 가지를 소개할게요.

FROM — 빌드가 확장할 베이스 이미지를 지정해요.
WORKDIR — "작업 디렉터리"를 지정해요. 파일이 복사되고 명령이 실행될 이미지 안의 경로예요.
COPY — 빌더에게 호스트에서 파일을 복사해 컨테이너 이미지에 넣으라고 지시해요.
RUN — 빌더에게 지정된 명령을 실행하라고 지시해요.
ENV — 실행 중인 컨테이너가 사용할 환경 변수를 설정해요.
EXPOSE — 이미지가 공개하고 싶어 하는 포트를 나타내는 구성을 이미지에 설정해요.
USER — 이후의 모든 지시문에 대한 기본 사용자를 설정해요.
CMD ["", ""] — 이 이미지를 사용하는 컨테이너가 실행할 기본 명령을 설정해요.

모든 지시문을 살펴보거나 더 자세히 알아보려면 Dockerfile 레퍼런스를 확인해 보세요.

직접 해보기

앞선 예시에서 봤듯이 Dockerfile은 보통 다음 단계를 따라요.

베이스 이미지 결정
애플리케이션 의존성 설치
관련 소스 코드 및/또는 바이너리 복사
최종 이미지 구성

이 빠른 실습 가이드에서는 간단한 Node.js 애플리케이션을 빌드하는 Dockerfile을 작성해요. JavaScript 기반 애플리케이션에 익숙하지 않아도 걱정하지 마세요. 이 가이드를 따라오는 데는 필요하지 않아요.

준비

이 ZIP 파일을 다운로드해 여러분의 머신의 디렉터리에 압축을 풀어요.

ZIP 파일을 다운로드하고 싶지 않다면 https://github.com/docker/getting-started-todo-app 프로젝트를 클론하고 build-image-from-scratch 브랜치를 체크아웃하세요.

Dockerfile 만들기

프로젝트가 준비됐으니 Dockerfile을 만들 차례예요.

Docker Desktop을 다운로드하고 설치해요.
프로젝트를 살펴봐요. getting-started-todo-app/app/의 내용을 탐색해 보세요. 이미 Dockerfile이 존재한다는 걸 알 수 있어요. 어떤 텍스트나 코드 편집기에서도 열 수 있는 간단한 텍스트 파일이에요.
기존 Dockerfile을 삭제해요. 이 실습에서는 처음부터 시작한다고 가정하고 새 Dockerfile을 만들 거예요.
getting-started-todo-app/app/ 폴더에 Dockerfile이라는 이름의 파일을 만들어요.

Dockerfile 파일 확장자 Dockerfile에는 파일 확장자가 없어요. 일부 편집기는 자동으로 확장자를 붙이려고 하거나(또는 확장자가 없다고 불평하기도 해요) 이 점에 유의하세요.
Dockerfile에 다음 줄을 추가해 베이스 이미지를 정의해요.
```
FROM node:22-alpine
```
이제 WORKDIR 지시문으로 작업 디렉터리를 정의해요. 이후 명령이 실행될 위치와 컨테이너 이미지 안에 디렉터리 파일이 복사될 위치를 지정해요.
```
WORKDIR /app
```
COPY 지시문으로 머신의 프로젝트에 있는 모든 파일을 컨테이너 이미지로 복사해요.
```
COPY . .
```
yarn CLI와 패키지 매니저로 앱의 의존성을 설치해요. RUN 지시문으로 명령을 실행하면 돼요.
```
RUN yarn install --production
```

마지막으로 CMD 지시문으로 실행할 기본 명령을 지정해요.

CMD ["node", "./src/index.js"]

이렇게 하면 다음과 같은 Dockerfile이 완성돼요.

FROM node:22-alpine
WORKDIR /app
COPY . .
RUN yarn install --production
CMD ["node", "./src/index.js"]

이 Dockerfile은 아직 프로덕션 준비가 되지 않았어요

이 Dockerfile은 아직 모든 모범 사례를 따르지 않고 있다는 점을 알아두세요. (의도적으로요.) 앱을 빌드하긴 하지만, 빌드가 최대한 빠르지 않고 이미지도 최대한 안전하지 않을 수 있어요.

계속 읽으면 빌드 캐시를 최대화하고, 비루트 사용자로 실행하며, 멀티 스테이지 빌드를 적용하는 방법을 배울 수 있어요.

추가 자료

Dockerfile 작성에 대해 더 알아보려면 다음 자료를 참고하세요.

Dockerfile 레퍼런스
Dockerfile 모범 사례
베이스 이미지
Gordon — Docker의 AI 어시스턴트가 여러분의 프로젝트를 위한 Dockerfile을 생성해 줄 수 있어요. Gordon에게 코드를 분석하고 언어와 프레임워크에 최적화된 Dockerfile을 추천해 달라고 요청해 보세요.

다음 단계

Dockerfile을 만들고 기본을 배웠으니, 이제 이미지를 빌드하고, 태그를 붙이고, 푸시하는 방법을 배울 차례예요.

Dockerfile 작성하기