Dockerfile 작성법

Dockerfile로 도커 이미지 만들기

도커의 가장 큰 장점 중 하나는 내가 원하는 환경을 그대로 정의한 이미지를 직접 만들 수 있다는 것입니다. 이 글에서는 Dockerfile을 이용해 간단한 파이썬 애플리케이션을 도커 이미지로 만들고 실행하는 실습을 진행합니다.

1. Dockerfile이란?

Dockerfile은 도커 이미지 생성 과정을 스크립트처럼 정의한 명령어 집합 파일입니다. 각 명령어는 이미지의 한 계층(layer)을 구성하며, Docker는 이 파일을 위에서 아래로 순서대로 읽고 실행하여 이미지를 생성합니다. 즉, Dockerfile은 ‘이미지를 만드는 레시피’라고 볼 수 있습니다.

Dockerfile은 다음과 같은 목적을 갖고 사용됩니다:

• 동일한 실행 환경을 누구나 쉽게 재현할 수 있도록 함
• 수동 설치나 설정 없이 자동화된 이미지 빌드 제공
• DevOps 파이프라인이나 배포 자동화에서 핵심 요소로 사용

Dockerfile 예시:

# 베이스 이미지 지정 (필수)
FROM python:3.12
# 이미지 빌드는 반드시 어떤 이미지로부터 시작해야 하므로 FROM은 Dockerfile의 첫 줄에 반드시 위치해야 합니다.

# 작업 디렉토리 생성 (옵션, 하지만 추천)
WORKDIR /app
# 컨테이너 내 작업 디렉토리를 설정합니다. 이후 COPY, RUN 등은 이 디렉토리 기준으로 동작합니다.

# 로컬 파일을 이미지 안으로 복사 (필수는 아님, 하지만 실질적으로 대부분 필요)
COPY hello.py .
# 실행 파일이나 소스코드, 설정파일 등을 이미지 내부로 복사합니다.

# 컨테이너가 실행될 때 기본 실행 명령 (필수는 아님, 하지만 기본 진입점이 없으면 컨테이너는 실행 후 종료됨)
CMD ["python", "hello.py"]
# 컨테이너가 실행될 때 실행할 기본 명령을 지정합니다. CMD는 Dockerfile 내에서 한 번만 사용할 수 있으며, 런타임 시 커맨드라인 인자로 override 가능합니다.

위 예제는 파이썬 3.12이 설치된 이미지 위에 hello.py 파일을 복사하고, 해당 파일을 실행하도록 설정된 Dockerfile입니다. 이처럼 Dockerfile을 활용하면 코드를 실행할 환경 전체를 명시적으로 정의할 수 있어 협업 및 배포에 큰 장점을 가집니다.

2. 예제 프로젝트 준비

hello.py 파일 만들기

print("Hello Docker container")

디렉토리 구조

my-docker-app/
├── Dockerfile
└── hello.py

3. 도커 이미지 빌드

터미널에서 해당 디렉토리로 이동한 후:

docker build -t hello-docker .

• -t hello-docker: 이미지 이름 설정
• .: 현재 디렉토리에 있는 Dockerfile 사용

이미지 빌드가 완료되면 docker images로 확인할 수 있습니다.

4. 이미지 실행 (컨테이너 실행)

docker run hello-docker

결과:

Hello Docker container

5. Dockerfile 명령어 정리

명령어	필수 여부	설명 및 특징	사용 예시
FROM	필수	어떤 이미지로부터 시작할지 지정. Dockerfile의 첫 줄에 위치해야 함.	FROM python:3.12
WORKDIR	옵션	작업 디렉토리를 설정. 이후 COPY, RUN 등 명령어 기준 경로가 됨.	WORKDIR /usr/src/app
COPY	옵션	로컬 파일을 이미지 내부로 복사. 코드, 설정파일, 리소스를 포함시킬 때 사용.	COPY . .
ADD	옵션	COPY와 비슷하지만 URL 다운로드 및 압축 해제 가능. 보통은 COPY를 권장.	ADD https://.../file.zip /tmp/
RUN	옵션	이미지 빌드 시 명령 실행. 패키지 설치, 빌드 작업 등에 사용.	RUN apt-get update && apt-get install -y curl
CMD	옵션	컨테이너가 실행될 때 기본 실행 명령. 한 번만 사용 가능.	CMD ["npm", "start"]
ENTRYPOINT	옵션	고정 실행 명령 지정. CMD는 인자처럼 전달됨.	ENTRYPOINT ["python"] + CMD ["app.py"]
ENV	옵션	환경 변수 설정.	ENV NODE_ENV=production
EXPOSE	옵션	컨테이너가 사용하는 포트 명시 (네트워크 연결에는 영향 없음).	EXPOSE 3000
ARG	옵션	빌드 시점에만 사용 가능한 변수 정의. ENV와 다르게 런타임엔 사용 불가.	ARG VERSION=1.0
LABEL	옵션	이미지에 메타데이터 추가. 예: 버전, 작성자 등.	LABEL maintainer="minjimanji@example.com"
VOLUME	옵션	컨테이너 외부와 데이터를 공유할 디렉토리 지정.	VOLUME ["/data"]
USER	옵션	컨테이너 내 명령을 실행할 사용자 지정. 기본은 root.	USER appuser
ONBUILD	옵션	해당 이미지를 기반으로 다른 이미지를 빌드할 때 실행되는 트리거 명령.	ONBUILD COPY . /app/src
SHELL	옵션	RUN, CMD 등에서 사용할 셸 지정 (기본은 /bin/sh -c).	SHELL ["/bin/bash", "-c"]

이 외에도 다양한 고급 옵션이 존재하지만, 위 명령어들이 Dockerfile 작성 시 가장 자주 사용되는 핵심들입니다.

6. 빌드 캐시와 이미지 계층 구조 이해

• Dockerfile 명령어 하나하나가 “이미지의 계층(layer)”으로 저장됩니다.
• 이전에 실행된 단계는 캐시로 재사용되어 빌드 속도가 빨라집니다.
• 변경이 잦은 명령어는 아래쪽에, 고정된 명령어는 위쪽에 두는 것이 빌드 최적화에 유리합니다.