DockerfileのENTRYPOINTとCMDを正しく使い分ける方法｜シェル形式・exec形式の設計指針と実践例

この記事のポイント

・ENTRYPOINT は「コンテナが必ず実行するプログラム」を固定する命令
・CMD は「ENTRYPOINT へのデフォルト引数」または単独のデフォルトコマンド
・exec形式（JSON配列）を使わないとシグナルが届かず docker stop が10秒かかる
・Compose では entrypoint: / command: キーで Dockerfile の設定を上書きできる

# Dockerfile（ENTRYPOINT のみ指定）
FROM ubuntu:22.04
ENTRYPOINT ["echo"]

# 動作確認
$ docker build -t entrypoint-only .
$ docker run entrypoint-only hello world
hello world

# 引数を渡さないと echo コマンドが引数なしで実行される（空行が出力される）
$ docker run entrypoint-only

# Dockerfile（CMD のみ指定）
FROM ubuntu:22.04
CMD ["echo", "Hello from CMD"]

# CMD がそのまま実行される
$ docker build -t cmd-only .
$ docker run cmd-only
Hello from CMD

# docker run に引数を渡すと CMD 全体が上書きされる（echo は実行されない）
$ docker run cmd-only /bin/bash -c "whoami"
root

# シェル形式の書き方（スペース区切りの文字列）
ENTRYPOINT nginx -g "daemon off;"
CMD echo "Hello"

# シェル形式の場合、PID 1 が sh になっている
$ docker exec mycontainer ps aux
USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         1  0.0  0.0   2888   968 ?        Ss   10:05   0:00 /bin/sh -c nginx -g daemon off;
root         7  0.0  0.1  54264  4256 ?        S    10:05   0:00 nginx: master process nginx -g daemon off;

# docker stop がタイムアウトまでかかる（10秒待ってから SIGKILL）
$ time docker stop mycontainer
mycontainer

real    0m10.126s

# exec形式の書き方（JSON配列）
ENTRYPOINT ["nginx", "-g", "daemon off;"]
CMD ["echo", "Hello"]

# exec形式の場合、PID 1 が nginx になっている
$ docker exec mycontainer ps aux
USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         1  0.0  0.1  54264  4256 ?        Ss   10:05   0:00 nginx: master process nginx -g daemon off;

# docker stop が即座に完了する（SIGTERM が nginx に届く）
$ time docker stop mycontainer
mycontainer

real    0m0.305s

# curl ツールをコンテナ化した Dockerfile
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y curl --no-install-recommends \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*
ENTRYPOINT ["curl"]
CMD ["--help"]

$ docker build -t my-curl .

# 引数なし → CMD の --help が使われる
$ docker run my-curl
Usage: curl [options...] 
 -d, --data    HTTP POST data
...

# URL を指定 → CMD が上書きされて指定の URL にリクエストする
$ docker run my-curl https://example.com



    
...

# JSON のレスポンスを整形して取得する
$ docker run my-curl -s https://api.example.com/status | python3 -m json.tool
{
    "status": "ok",
    "version": "1.2.3"
}

# CMD を上書きして別のオプションを渡す
$ docker run my-curl -I https://example.com
HTTP/2 200
content-type: text/html; charset=UTF-8
...

# ENTRYPOINT を bash で上書きしてコンテナ内に入る
$ docker run --entrypoint /bin/bash -it my-curl
root@a1b2c3d4e5f6:/#

# コンテナ内から curl が使えるか確認する
root@a1b2c3d4e5f6:/# curl --version
curl 7.81.0 (x86_64-pc-linux-gnu) libcurl/7.81.0 ...

# docker-compose.yml での上書き例
services:
  curl:
    image: my-curl
    # コンテナを起動したまま待機させてデバッグに使う
    entrypoint: ["/bin/bash", "-c"]
    command: ["while true; do sleep 60; done"]

# ENTRYPOINTをbashに上書きしてコンテナ内に入る
# compose.ymlの environment / volumes / networks 設定は引き継がれる
$ docker compose run --rm --entrypoint bash web

root@f2a3b4c5d6e7:/app# env | grep APP
APP_ENV=production
APP_VERSION=1.2.0

# 確認が終わったら exit（--rm でコンテナは自動削除される）
root@f2a3b4c5d6e7:/app# exit

# 稼働中の web サービスにシェルで入る
$ docker compose exec web bash
root@a1b2c3d4e5f6:/app#

# Dockerfile で USER が設定されていても root として入る（--user オプション）
$ docker compose exec --user root web bash
root@a1b2c3d4e5f6:/app# id
uid=0(root) gid=0(root) groups=0(root)

# ワンライナーでコンテナ内のコマンドを実行する
$ docker compose exec web python manage.py showmigrations

#!/bin/bash
# docker-entrypoint.sh

set -e

# 必須の環境変数を検証する
if [ -z "$APP_ENV" ]; then
  echo "ERROR: APP_ENV が未設定です。起動を中止します。" >&2
  exit 1
fi

echo "INFO: APP_ENV=${APP_ENV} でサーバーを起動します"

# envsubst で設定テンプレートの変数を置換する
envsubst '${APP_ENV} ${SERVER_NAME}' \
  < /etc/nginx/nginx.conf.template \
  > /etc/nginx/nginx.conf

# exec で CMD（ENTRYPOINT の後続引数）を実行する
# exec を使うことで nginx が PID 1 を引き継いでシグナルを受け取れる
exec "$@"

FROM nginx:1.27-alpine

# envsubst のために gettext をインストールする
RUN apk add --no-cache gettext

# エントリーポイントスクリプトをコピーして実行権限を付与する
COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
RUN chmod +x /usr/local/bin/docker-entrypoint.sh

# 設定ファイルのテンプレートをコピーする
COPY nginx.conf.template /etc/nginx/nginx.conf.template

# スクリプトを ENTRYPOINT に設定する（exec形式必須）
ENTRYPOINT ["docker-entrypoint.sh"]

# デフォルトでは nginx をフォアグラウンド実行する
CMD ["nginx", "-g", "daemon off;"]

$ docker build -t my-nginx .

# 正常起動（APP_ENV を設定）
$ docker run -d \
    -e APP_ENV=production \
    -e SERVER_NAME=www.example.com \
    -p 8080:80 \
    --name web \
    my-nginx
INFO: APP_ENV=production でサーバーを起動します
...

# 環境変数なし → エラーで起動を停止する
$ docker run my-nginx
ERROR: APP_ENV が未設定です。起動を中止します。

# graceful stop が機能しているか確認する（即座に停止する）
$ time docker stop web
web

real    0m0.318s

# NG: シェル形式（PID 1 が sh になる）
ENTRYPOINT nginx -g "daemon off;"

# OK: exec形式（PID 1 が nginx になる）
ENTRYPOINT ["nginx", "-g", "daemon off;"]

# NG: ENTRYPOINT がシェル形式 → CMD は無視される
ENTRYPOINT echo
CMD ["Hello"]   # 無視される（echo が引数なしで実行される）

# OK: 両方 exec形式
ENTRYPOINT ["echo"]
CMD ["Hello"]   # "Hello" が echo に渡されて "Hello" と出力される

# Dockerfile で実行権限を付与する（必須）
COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
RUN chmod +x /usr/local/bin/docker-entrypoint.sh

# Windows で作成したスクリプトの改行コードを LF に変換する
$ sed -i 's/\r//' docker-entrypoint.sh

# スクリプトの先頭が正しい shebang になっているか確認する
$ head -1 docker-entrypoint.sh
#!/bin/bash

# CI から実行するとエラーになるパターン
$ docker compose exec web python manage.py migrate
the input device is not a TTY

# 修正後（-T を追加して TTY を無効化）
$ docker compose exec -T web python manage.py migrate
Operations to perform:
  Apply all migrations: accounts, admin, auth
Running migrations:
  Applying accounts.0001_initial... OK

# コンテナの出力をパイプで受け取る場合も -T が必要
$ docker compose exec -T db pg_dump -U postgres myapp | gzip > backup.sql.gz

＜PR＞手元に置いて学びを深める1冊

Docker/Kubernetes実践コンテナ開発入門 改訂新版

DockerfileのENTRYPOINT・CMD設計からコンテナ本番運用まで体系的に学べる一冊。記事で解説した概念をより深く掘り下げたい方に。