Dockerfile の基本命令 - Dockerfile instructions

Dockerfile の命令リファレンス。FROM でベースを決め、RUN・COPY・WORKDIR・ENV・CMD・ENTRYPOINT を順番に並べる。

概念図

構文

bash

FROM <image>[:<tag>]
RUN <command>
COPY [--chown=<user>:<group>] <src>... <dest>
WORKDIR <path>
ENV <key>=<value>
CMD ["executable", "param1", "param2"]
ENTRYPOINT ["executable", "param1", "param2"]

実例

Node.js アプリの最小構成。package.json を先に COPY してキャッシュを活かす

bash

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
ENV NODE_ENV=production
CMD ["node", "server.js"]

ENTRYPOINT で実行コマンドを固定し、CMD でデフォルト引数を渡す

bash

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
ENTRYPOINT ["python", "-m", "app"]
CMD ["--port", "8000"]

基本命令の流れ

Dockerfile は上から下へ順に評価される。

最初に FROM でベースイメージを決め、続いて WORKDIR で作業ディレクトリを固定し、COPY でソースを取り込み、RUN で依存解決やコンパイルを行い、ENV で環境変数を設定し、最後に CMD か ENTRYPOINT で起動コマンドを定義する。

各命令はレイヤーとなりキャッシュされるため、順序と粒度がビルド時間とイメージサイズに直結する。

WORKDIR を省略すると / がカレントディレクトリになり、相対パス指定が壊れやすい。

RUN は && でまとめると中間レイヤーを減らせる。

bash

FROM debian:bookworm-slim
WORKDIR /srv/app
ENV LANG=C.UTF-8
RUN apt-get update \
 && apt-get install -y --no-install-recommends curl ca-certificates \
 && rm -rf /var/lib/apt/lists/*
COPY ./bin/app /usr/local/bin/app
CMD ["/usr/local/bin/app"]

CMD と ENTRYPOINT の違い

CMD は「デフォルトの引数」、ENTRYPOINT は「固定の実行コマンド」に使う。

docker run image arg1 のように引数を渡すと、CMD のみの場合は CMD 全体が arg1 で上書きされる。

一方 ENTRYPOINT が定義されていると、arg1 は ENTRYPOINT の引数として追加される。

CLI ツールとして振る舞わせたいイメージは ENTRYPOINT にバイナリを固定し、CMD で既定オプションを書く構成が扱いやすい。

シェル形式（CMD command）は sh -c 経由で実行されシグナルが届きにくいので、JSON 配列形式（exec 形式）を推奨する。

bash

# CLI として振る舞わせる
ENTRYPOINT ["/usr/local/bin/myctl"]
CMD ["--help"]

# docker run myimage            -> /usr/local/bin/myctl --help
# docker run myimage status     -> /usr/local/bin/myctl status

COPY と ADD の使い分け

COPY と ADD の主な違いは以下。

COPY: ローカルファイルをコンテナに取り込むだけのシンプルな命令。挙動が予測しやすい
ADD: COPY の機能に加えて、URL からのダウンロードと tar アーカイブの自動展開という副作用を持つ
副作用の落とし穴: ビルドが外部 URL に依存したり、意図せず中身が展開されたりして事故の原因になる
原則: COPY を使い、tar 展開が必要なときだけ ADD を使う
URL からの取得: RUN curl -L と sha256sum での検証を組み合わせたほうが検証可能性が高い
--chown / --chmod: COPY でも利用できる

bash

# 推奨: COPY + 検証付き取得
COPY --chown=app:app ./src /srv/app
RUN curl -fsSL https://example.com/tool.tar.gz -o /tmp/tool.tgz \
 && echo "<sha256>  /tmp/tool.tgz" | sha256sum -c - \
 && tar -xzf /tmp/tool.tgz -C /opt \
 && rm /tmp/tool.tgz

概念図

構文

実例

基本命令の流れ

CMD と ENTRYPOINT の違い

COPY と ADD の使い分け

関連トピック