Dockerfile 인스트럭션 레퍼런스

Dockerfile 스크립트를 작성하고 이 스크립트를 빌드해 이미지를 만들 수 있다.

#빌드 명령어 형식

docker build -t [생성할 이미지 이름] [빌드 컨텍스트 경로]

# 신형(관리 명령어) 방식
docker image build -t [생성할 이미지 이름] [빌드 컨텍스트 경로]

# 예시 — 현재 디렉터리를 컨텍스트로, 그 안의 Dockerfile 을 쓴다
docker build -t myapp .

docker build -t myapp ./Dockerfile     # 하지 말 것
# unable to prepare context: path "./Dockerfile" not found

docker build -t myapp -f docker/Dockerfile-prod .

#FROM — 기본 이미지를 지정

# 사용문법
FROM [--platform=<platform>] <image>[:<tag>] [AS <name>]

# 예시
FROM ubuntu:24.04

# syntax=docker/dockerfile:1
ARG JAVA_VERSION=21
FROM eclipse-temurin:${JAVA_VERSION}-jre

#RUN — 명령어 실행

이미지 빌드 시점에 실행된다.

# 사용문법
RUN <command>
RUN ["executable", "param1", "param2"]

# 예시
RUN apt-get update
RUN /bin/bash -c 'source $HOME/.bashrc; echo $HOME'
RUN ["/bin/bash", "-c", "echo hello"]

RUN apt-get update && \
    apt-get install -y --no-install-recommends curl && \
    rm -rf /var/lib/apt/lists/*

#CMD — 컨테이너 생성 시 실행할 명령어

Dockerfile 내에 여러 개가 있어도 마지막 CMD 하나만 유효하다.

# 사용문법
CMD ["executable","param1","param2"]
CMD ["param1","param2"]
CMD command param1 param2

# 예시
CMD echo "This is a test." | wc -
CMD ["/usr/bin/wc","--help"]

CMD는 컨테이너 실행 시 단일 기본 명령어를 지정하는 용도로 사용되며, 필요 시 ENTRYPOINT와 조합하여 사용할 수 있다.

FROM ubuntu:24.04

ENTRYPOINT ["echo"]
CMD ["Hello from CMD"]

#ENTRYPOINT — 컨테이너 구성 시 기본 실행 명령어

docker run 뒤에 인자를 붙여도 교체되지 않고, 붙인 내용이 ENTRYPOINT의 인자로 전달된다. 단, 이것은 exec form(JSON 배열)일 때만 그렇다.

# 사용문법
ENTRYPOINT ["executable", "param1", "param2"]
ENTRYPOINT command param1 param2

# 예시
ENTRYPOINT ["/usr/sbin/apache2ctl", "-D", "FOREGROUND"]

ENTRYPOINT java -jar app.jar          # 하지 말 것
ENTRYPOINT ["java", "-jar", "app.jar"]  # 이렇게 쓴다

#🔬 직접 해 보기 — 인자가 교체되는지 확인한다

위 표를 손으로 확인한다. Dockerfile 두 개를 만든다.

# Dockerfile.cmd — CMD 만 있다
FROM alpine:3.20
CMD ["echo", "[CMD 만 있음]"]

# Dockerfile.both — ENTRYPOINT + CMD
FROM alpine:3.20
ENTRYPOINT ["echo", "[ENTRYPOINT]"]
CMD ["[CMD]"]

docker image build -f Dockerfile.cmd  -t demo-cmd  .
docker image build -f Dockerfile.both -t demo-both .

인자를 붙이지 않았을 때와 붙였을 때를 비교한다.

docker container run --rm demo-cmd
docker container run --rm demo-cmd whoami
docker container run --rm demo-both
docker container run --rm demo-both 안녕

[CMD 만 있음]
root
[ENTRYPOINT] [CMD]
[ENTRYPOINT] 안녕

두 번째 줄이 핵심이다. demo-cmd whoami 가 [CMD 만 있음] whoami 가 아니라 root 를 출력한다. CMD 는 인자를 받는 것이 아니라 통째로 밀려난다. 반면 demo-both 안녕 은 [ENTRYPOINT] 를 그대로 둔 채 CMD 자리만 바꾼다.

docker image rm demo-cmd demo-both

#EXPOSE — 컨테이너에서 사용할 포트 정보

실제로 포트를 여는 것은 아니며, docker run 실행 시 -p 옵션을 사용하여 포트를 열어주어야 한다.

# 사용문법
EXPOSE <port> [<port>/<protocol>...]

# 예시
EXPOSE 9000

#ENV — 환경 변수를 설정

빌드 시점과 컨테이너 실행 시점 모두에서 사용 가능하다.

# 사용문법
ENV <key>=<value> ...

# 예시
ENV MY_NAME="John Doe"
ENV MY_DOG=Rex\ The\ Dog
ENV MY_CAT=fluffy

#ARG — 빌드 시 환경변수 설정

빌드 시점에만 존재한다. docker build --build-arg 로 값을 전달한다.

ARG JDK=21
FROM eclipse-temurin:${JDK}-jre   # 여기서는 쓸 수 있다
ARG JDK                           # 다시 선언해야 아래에서 쓸 수 있다
RUN echo "JDK=${JDK}"

# 사용문법
ARG <name>[=<default value>]

# 예시
FROM busybox
ARG user1=someuser
ARG buildno=1

#🔬 직접 해 보기 — ARG 로 넘긴 값은 이미지에 남는다

"이미지 히스토리에 남을 수 있다" 를 눈으로 확인한다.

FROM alpine:3.20
ARG DB_PASSWORD
RUN echo "빌드 중 비밀번호 사용: $DB_PASSWORD" > /tmp/x

docker image build --build-arg DB_PASSWORD=hunter2 -t arg-demo .
docker image history --no-trunc arg-demo | grep DB_PASSWORD

RUN |1 DB_PASSWORD=hunter2 /bin/sh -c echo "빌드 중 비밀번호 사용: $DB_PASSWORD" > /tmp/x   12.3kB
ARG DB_PASSWORD=hunter2                                                                     0B

평문으로, 그것도 두 줄에 남는다. RUN 에서 그 값을 쓰지 않았더라도 ARG 줄은 남는다. 이미지를 받은 사람은 누구나 볼 수 있고, 레지스트리에 한 번 올렸다면 이미지를 지워도 안전해지지 않는다 — 값 자체를 폐기하고 새로 발급해야 한다.

docker image rm arg-demo

#ADD — 외부 파일 또는 디렉토리 추가

COPY와 유사하지만 URL 다운로드·압축 해제 기능이 추가되어 있다.

# 사용문법
ADD [--chown=<user>:<group>] <src>... <dest>
ADD [--chown=<user>:<group>] ["<src>",... "<dest>"]

# 예시
ADD test.txt relativeDir/
ADD test.txt /absoluteDir/

#COPY — 외부 파일 또는 디렉터리를 복사

동작이 명시적이라 대부분의 경우 ADD보다 COPY를 권장한다.

# 사용문법
COPY [--chown=<user>:<group>] <src>... <dest>
COPY [--chown=<user>:<group>] ["<src>",... "<dest>"]

# 예시
COPY test.txt relativeDir/
COPY test.txt /absoluteDir/

# 멀티 스테이지 빌드에서 다른 단계의 결과물 복사
COPY --from=builder /build/app.jar app.jar

#VOLUME — 마운트 지점을 생성

FROM ubuntu
RUN mkdir /myvol
RUN echo "hello world" > /myvol/greeting
VOLUME /myvol

#USER — RUN, CMD, ENTRYPOINT를 실행하는 사용자

# 사용문법
USER <user>[:<group>]
USER <UID>[:<GID>]

# 예시
FROM ubuntu:24.04
# 컨테이너 안에 사용자를 만들고
RUN useradd --create-home patrick
# 이후 명령을 그 사용자로 실행한다
USER patrick

#WORKDIR — 작업 디렉토리 설정

# 예시
WORKDIR /path/to/workdir

# 디렉토리가 없으면 생성한다.
# CMD, COPY, RUN 등의 명령어를 실행하기 전에 작업 디렉토리를 변경할 때 사용

WORKDIR /app
WORKDIR build      # 결과는 /app/build

#🔬 직접 해 보기 — WORKDIR 는 쌓이고, RUN cd 는 안 남는다

위 두 가지를 한 번에 확인한다.

FROM alpine:3.20
WORKDIR /app
WORKDIR build
RUN cd /tmp
RUN pwd > /where.txt
CMD ["cat", "/where.txt"]

docker image build -t workdir-demo .
docker container run --rm workdir-demo

/app/build

두 가지가 동시에 드러난다.

• WORKDIR build 가 /build 가 아니라 /app/build 다. 상대 경로는 직전 WORKDIR 에 붙는다.

• 바로 위에 RUN cd /tmp 가 있는데도 /tmp 가 아니다. cd 는 그 RUN 안에서 끝난다.

docker image rm workdir-demo

#LABEL — 이미지에 메타데이터 붙이기

# 사용문법
LABEL <key>=<value> <key>=<value> ...

# 예시
LABEL org.opencontainers.image.source="https://github.com/kaeback/visit-counter"
LABEL org.opencontainers.image.description="방문자 카운터"

docker image inspect 로 확인한다. GHCR 은 org.opencontainers.image.source 를 보고 패키지를 저장소에 연결하므로, 이 한 줄이 있으면 패키지 페이지에서 소스로 바로 넘어간다.

#HEALTHCHECK — 컨테이너가 살아 있는지 판정

# 사용문법
HEALTHCHECK [OPTIONS] CMD <command>
HEALTHCHECK NONE

# 예시
HEALTHCHECK --interval=10s --timeout=3s --start-period=40s --retries=3   CMD curl -fsS http://localhost:8080/actuator/health || exit 1

명령의 종료 코드로 판정한다 — 0 이면 정상, 1 이면 비정상. 결과는 docker ps 의 STATUS 에 (healthy) / (unhealthy) 로 나온다.

#STOPSIGNAL — 종료 시 보낼 시그널

# 사용문법
STOPSIGNAL <signal>

# 예시
STOPSIGNAL SIGTERM

기본값은 SIGTERM 이다. docker stop 은 이 시그널을 보내고 기본 10초를 기다린 뒤 응답이 없으면 SIGKILL 로 강제 종료한다. 기다리는 시간은 docker stop -t 30 으로 늘린다.

시그널이 애플리케이션까지 닿으려면 PID 1 이 애플리케이션이어야 한다. ENTRYPOINT 를 shell form 으로 쓰면 PID 1 이 sh 가 되어 여기서 끊긴다.

#실습은 어디에 있나

이 문서 안의 🔬 직접 해 보기 는 인스트럭션 하나의 동작을 확인하는 짧은 것들이다.

이미지를 처음부터 설계하고 빌드해 배포하는 본 실습은 이미지 생성 및 관리에 있다. 멀티 스테이지 빌드로 visit-counter 이미지를 만들고 Docker Hub 에 올린다.