Dockerfileの命令を1つずつ読む — EXPOSEを書いてもポートは開かない

Dockerfileを1行ずつ読む。Dockerfileの書類とコンテナ、虫眼鏡。

※本記事はアフィリエイト広告(PR)を含みます。

EXPOSEを書いてもポートは開きません。Dockerfileの命令を1つずつ読んで、何をしているのかを確かめます。

前回: コンテナとVMの違いを測る — 軽いのはOSを起動しないから

これは深掘りです。本線の順路ではありません。 本線のDockerの導入とCompose の回で他人が作ったイメージを動かせるようになった人が、「自分のアプリをイメージにしたいが、Dockerfile の中身が読めない」ところで止まったときに読む記事です。飛ばしても本線は進みます。

この記事のコマンドは、すべて Ubuntu Server(VM)の中で打ちます。 Windows の PowerShell ではありません。 プロンプトが ユーザー名@ホスト名:~$ の形になっていれば、Linux の中にいます。 前回入れた Docker がそのまま使えることが前提です。docker version が返らない場合は、本線のDockerの導入に戻ってください。

対象レベル: 中級〜上級 / 区分: 発展

目次

コピーしたら動いた。それで終わりにしていた

Node.js のアプリをコンテナにしようとして、検索して出てきた Dockerfile をそのまま貼りました。

FROM node:18
WORKDIR /usr/src/app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 8080
CMD npm start

動きました。 それで満足して閉じたのですが、あとで困ったことが3つ起きました。

  1. EXPOSE 8080 と書いてあるのに、ブラウザから 8080 番で繋がらない
  2. docker stop を押してから、毎回きっかり10秒くらい止まらない
  3. ソースを1文字直しただけなのに、npm install がまた最初から走る

3つとも、この Dockerfile の書き方が原因でした。 そして3つとも、「その行が何をしているのか」を知らないまま貼ったから起きています。

この記事では、まっさらな1行の Dockerfile から始めて、命令を1つずつ足し、そのたびにビルドして結果を見ます。 動くものを作るのが目的ではなく、1行足したときにイメージがどう変わるかを見るのが目的です。

この記事でわかること

  • タグを省くと latest になるが、latest は「最新版」という名前のただのタグであって、固定されていないこと。同じ Dockerfile が来月違う結果になる理由
  • RUN cd /app は次の行に効かないこと。ディレクトリを移すのは WORKDIR の仕事で、これは「行儀の問題」ではなく仕組みの問題であること
  • ADD は URL を取ってきたり、tar を勝手に展開したりすること。だから驚きの少ない COPY を使うという判断になること
  • EXPOSE はポートを開かないこと。あれは人と道具に向けたドキュメントで、外から繋ぐのは -p の仕事であること
  • ENV は実行時にも残り、ARG はビルド時だけであること。ただしARG に秘密情報を渡すとイメージの履歴に残ること
  • CMD を shell形式で書くと /bin/sh が PID 1 になり、docker stop のシグナルがアプリに届かないこと。その結果10秒待たされること
  • .dockerignore を書かないと node_modules と .env がビルドに送られること。それがキャッシュを壊す側面もあること

この記事でやること

  1. ~/dockerlab に、/ に文字を返すだけの小さな Express アプリを新しく作る(既存の ~/server や ~/hitokoto は触りません)
  2. FROM だけの Dockerfile から始めて、WORKDIR COPY RUN ENV ARG EXPOSE CMD を1つずつ足しては毎回ビルドする
  3. shell形式と exec形式で docker stop にかかる時間を実際に測る
  4. .dockerignore を書いて、ビルドに送られるサイズが変わるのを実測する
  5. docker build --progress=plain と docker history で、どの行がキャッシュに当たり、どの行が何MB増やしたかを見る
  6. HEALTHCHECK と USER を足し、hadolint に検査させてから、全部片づける

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
Dockerfileイメージの作り方を上から順に書いたテキストファイル。拡張子は無いのが普通
ビルドコンテキストdocker build に渡すフォルダのこと。その中身が丸ごと Docker に送られてからビルドが始まる
レイヤーイメージを構成する「差分の層」。RUN COPY ADD の1行ごとに1枚できる
タグnode:22-slim の : から後ろ。イメージの版につけた名札で、中身と1対1ではない
ダイジェストsha256:... の形の、中身から計算した指紋。これは中身と1対1で、書き換わらない
exec形式CMD ["node", "server.js"] のように配列で書く形。シェルを通さず、そのまま実行する
shell形式CMD node server.js のように文字列で書く形。/bin/sh -c に渡される
PID 1コンテナの中で最初に起動したプロセス。docker stop のシグナルはここに届く
BuildKitいまの Docker が既定で使うビルドの仕組み。出力の見た目が昔の記事と違うのはこれが理由
hadolintDockerfile 専用の検査ツール。書き方の定番の失敗を指摘する

練習場を作る

既存の ~/server や ~/hitokoto は一切触りません。 新しく ~/dockerlab を作り、そこだけで完結させます。

bash
$ mkdir -p ~/dockerlab
$ cd ~/dockerlab
$ pwd

確認: pwd が /home/ユーザー名/dockerlab になっていれば準備完了です。

アプリ本体(2ファイルだけ)

中身は「/ を開くと文字が返るだけ」です。 小さいほど、Dockerfile の1行ずつの効果が見やすくなります。

まず package.json を作ります。

bash
$ nano package.json

このファイルの全文です。

{
  "name": "dockerlab",
  "version": "1.0.0",
  "private": true,
  "description": "Dockerfile を1行ずつ確かめるための最小アプリ",
  "main": "server.js",
  "scripts": {
    "start": "node server.js"
  },
  "dependencies": {
    "express": "^4.21.2"
  }
}

Ctrl + O → Enter で保存、Ctrl + X で閉じます。

次が server.js です。

bash
$ nano server.js

このファイルの全文です。

const express = require('express');

const app = express();
const port = process.env.PORT || 3000;
const greeting = process.env.GREETING || 'hello from dockerlab';

app.get('/', (req, res) => {
  res.type('text/plain').send(greeting + '\n');
});

app.get('/healthz', (req, res) => {
  res.type('text/plain').send('ok\n');
});

app.listen(port, '0.0.0.0', () => {
  console.log('listening on ' + port);
});

// docker stop の SIGTERM を受けたら終わる(PID 1 では、書かないと無視される)
process.on('SIGTERM', () => process.exit(0));

3か所だけ、後で効いてきます。

場所後でどう効くか
process.env.PORTENV で入れた値が実行時に読めることの確認に使う
process.env.GREETINGARG と ENV の違いを目で見るのに使う
/healthzHEALTHCHECK の宛先に使う

0.0.0.0 で待ち受けているのが重要です。 ここを 127.0.0.1 にすると、コンテナの中からしか繋がらず、-p でポートを繋いでも外から見えません。本線のnginxのリバースプロキシで出てきた「どのアドレスで待つか」と同じ話です。

依存を入れる(VM に Node.js が無くてもできる)

express を使うので node_modules が要ります。VM に Node.js を入れていなくても構いません。 Docker の中の node で npm install を回します。

bash
$ docker run --rm -v ~/dockerlab:/app -w /app node:22-slim npm install
added 65 packages, and audited 66 packages in 3s
found 0 vulnerabilities

このコマンドが何をしたか、1つずつ読みます。

部分意味
--rm終わったらコンテナを消す。使い捨て
-v ~/dockerlab:/appVM の ~/dockerlab を、コンテナの中の /app として見せる
-w /appコンテナの中の作業ディレクトリを /app にする(後で出てくる WORKDIR と同じ役割)
node:22-slim npm installそのイメージで npm install を実行する

結果を見ます。

bash
$ ls -a
$ du -sh node_modules
.  ..  node_modules  package-lock.json  package.json  server.js
2.3M	node_modules

package-lock.json が増えているのを確認してください。 後で npm ci を使うときに必要になります。

node_modules の中身は VM 側に残ります。 コンテナは消えても、マウントした場所に書いたものは残るからです。これは本線の Compose の回で見た「ボリュームに書いたものは消えない」と同じ理屈です。

秘密っぽいファイルも1つ置く

後で .dockerignore の効果を確かめるために、入ってはいけないファイルをわざと置いておきます。

bash
$ echo "SECRET_TOKEN=do-not-ship-me" > .env
$ cat .env

確認: SECRET_TOKEN=do-not-ship-me と返れば置けています。これは練習用のダミーです。本物のパスワードは書かないでください。

手元の VM ごと分けて、壊しても本線に影響しない練習場が欲しい場合は、VPS を 1 台借りる方法もあります。さくらのVPSはクレジットカード払いなら全プラン 2 週間無料で試せます(2026-11 時点の公式案内。お試し中は外向き通信が 10Mbps に制限され、解約しないと自動で本登録になります)。最低利用期間は 3 ヶ月なので、続けるかどうかは試用中に決めておくと安心です。

FROM — 1行だけの Dockerfile を作る

ここから、命令を1つずつ足していきます。 いきなり完成形を書きません。

bash
$ nano Dockerfile

この1行だけです。

FROM node:22-slim

ビルドします。

bash
$ docker build -t dockerlab:v1 .
[+] Building 12.4s (5/5) FINISHED
 => [internal] load build definition from Dockerfile
 => [internal] load metadata for docker.io/library/node:22-slim
 => [internal] load .dockerignore
 => [1/1] FROM docker.io/library/node:22-slim@sha256:...
 => exporting to image
 => => naming to docker.io/library/dockerlab:v1

確認: 最後が naming to docker.io/library/dockerlab:v1 で終わっていれば成功です。

bash
$ docker image ls dockerlab
REPOSITORY   TAG   IMAGE ID       CREATED          SIZE
dockerlab    v1    9a3b1c4d5e6f   10 seconds ago   225MB

まだ何もしていないのに 225MB あります。 これは node:22-slim の中身がそのまま自分のイメージになっているからです。

docker build の最後にある . を忘れないでください。 これは「このフォルダをビルドコンテキストとして送る」という意味です。-t の後ろのタグ名と混ざりやすいですが、別の引数です。

タグを省くと latest になる。そして latest は固定ではない

FROM node と書くと FROM node:latest と同じ意味になります。問題は、latest が「いつも最新」を保証する仕組みではないことです。

latest は、ただのタグ名です。 慣習で「新しいものに付け替える」運用がされているだけで、中身は公開側の都合でいつでも差し替わります。

軽いイメージで実際に見ます。

bash
$ docker run --rm alpine:latest cat /etc/os-release
NAME="Alpine Linux"
ID=alpine
VERSION_ID=3.22.1
PRETTY_NAME="Alpine Linux v3.22"
bash
$ docker run --rm alpine:3.20 cat /etc/os-release
NAME="Alpine Linux"
ID=alpine
VERSION_ID=3.20.6
PRETTY_NAME="Alpine Linux v3.20"

alpine:latest が指している中身は、この記事を書いた日と、あなたが読んでいる日で違う可能性があります。 alpine:3.20 は違います。

これが何を壊すか。

半年前に動いていた Dockerfile が、1文字も変えていないのに今日は失敗する。

原因を探しても、自分のリポジトリの差分はゼロです。動いていないのは自分のコードではなく、足元の OS が入れ替わったからです。

書き方どうなるか
FROM nodelatest が指すもの。いつ何に変わるか分からない
FROM node:22メジャー版は固定。22.x の中では動く
FROM node:22-slimこの記事で使う形。版と、中身の量(slim)を両方決めている
FROM node:22-slim@sha256:...ダイジェストで固定。同じものしか来ない。再現性は最強だが、更新は手で上げる

いま自分が何を掴んだのかは、こう見えます。

bash
$ docker image ls --digests node
REPOSITORY   TAG        DIGEST                     IMAGE ID       SIZE
node         22-slim    sha256:c7f4a2e1...         5b2e9d1f0a3c   225MB

slim は「小さい版」です。 通常の node:22 は 1.1GB 前後ありますが、ビルドに使う道具(コンパイラなど)が全部入っているためです。動かすだけなら要りません。

[スクリーンショット: 01_from_build.png] docker build -t dockerlab:v1 . を実行して、最後に naming to docker.io/library/dockerlab:v1 と出ている画面を撮ってください。

WORKDIR — RUN cd は次の行に効かない

ここが最初のつまずきポイントです。 「フォルダを移りたいから cd を書く」は、Dockerfile では通用しません。実演します。

bash
$ nano Dockerfile
FROM node:22-slim

RUN mkdir /app
RUN cd /app
RUN pwd
bash
$ docker build -t dockerlab:v2 .
 => [2/4] RUN mkdir /app
 => [3/4] RUN cd /app
 => [4/4] RUN pwd
#7 0.213 /

RUN pwd の結果が /app ではなく / です。 エラーは1つも出ていません。黙って効いていないのが、たちの悪いところです。

理由は「1行が1つのコンテナだから」です。

RUN は1行ごとに、新しいコンテナを立てて、コマンドを実行して、その差分をレイヤーとして保存し、コンテナを捨てています。

cd /app はそのコンテナの中のプロセスの現在地を変えただけで、変えたプロセスごと消えています。残るのはファイルの差分だけなので、「どこにいたか」は次の行に引き継がれません。

正しくは WORKDIR を使います。

FROM node:22-slim

WORKDIR /app
RUN pwd
bash
$ docker build -t dockerlab:v2 .
 => [2/3] WORKDIR /app
 => [3/3] RUN pwd
#7 0.198 /app

今度は /app です。

WORKDIR は3つのことを同時にやります。

やること補足
そのディレクトリに移動する以降の RUN COPY CMD すべてに効く
無ければ作るmkdir -p 相当。先に RUN mkdir を書く必要はない
相対パスの基準になるCOPY . . の2つ目の . は、ここになる

同じ RUN の中でなら cd は効きます。 RUN cd /app && pwd は /app を返します。行をまたげないだけです。

COPY と ADD — 驚きの少ないほうを選ぶ

ファイルをイメージに入れる命令は2つあります。ほぼ同じに見えますが、ADD は余計なことをします。

まず COPY です。

FROM node:22-slim

WORKDIR /app
COPY package.json ./
RUN ls -l
bash
$ docker build -t dockerlab:v3 .
 => [4/4] RUN ls -l
#8 0.201 total 4
#8 0.201 -rw-r--r-- 1 root root 291 Sep 21 09:12 package.json

package.json が1個だけ入りました。 これが COPY の全部です。手元のファイルを、そこに置く。それだけ。

ADD が勝手にやること

ADD は同じ書き方で動きますが、引数の形によって挙動が変わります。 実際に見ます。

bash
$ cd ~/dockerlab
$ mkdir -p sample && echo "inside the tarball" > sample/note.txt
$ tar czf sample.tar.gz sample
$ ls -lh sample.tar.gz
-rw-rw-r-- 1 user user 141 Sep 21 09:15 sample.tar.gz
FROM node:22-slim

WORKDIR /app
ADD sample.tar.gz ./
RUN ls -R /app
bash
$ docker build -t dockerlab:v3add .
 => [4/4] RUN ls -R /app
#8 0.204 /app:
#8 0.204 sample
#8 0.204
#8 0.204 /app/sample:
#8 0.204 note.txt

sample.tar.gz というファイルは、イメージの中に存在しません。 ADD が勝手に展開して、中身の sample/note.txt だけを置きました。

COPY で同じことをすると、こうなります。

FROM node:22-slim

WORKDIR /app
COPY sample.tar.gz ./
RUN ls -l /app
#8 0.199 -rw-r--r-- 1 root root 141 Sep 21 09:15 sample.tar.gz

COPY は圧縮ファイルを圧縮ファイルのまま置きます。 書いたとおりです。

ADD の挙動をまとめます。

渡したものADD の動きCOPY の動き
普通のファイルそのまま置くそのまま置く
ローカルの tar.gz展開して置く(ファイル自体は残らない)そのまま置く
URLダウンロードして置く(展開はしない)エラー(URL は受け付けない)
リモートの Git リポジトリクローンして置くエラー

「便利そう」に見えますが、これは事故のもとです。

  • ビルドの中でネットに取りに行っているのに、Dockerfile を見ただけでは気づきにくい。取得先が消えたらビルドが落ちる
  • URL 取得のときはキャッシュの判定が緩く、中身が変わっても気づかないことがある
  • .tar.gz をそのまま配りたいだけなのに展開される

判断はこうです。

迷ったら COPY。展開したいなら COPY してから RUN tar と書く。 ネットから取るなら RUN curl と書く。何をしているかが行に見えているほうがいい。

ADD を使ってよい場面もあります。 ローカルの tar を展開して置くのは、COPY + RUN tar よりレイヤーが1枚少なくなるためです。ただしそれは分かった上で選ぶ話で、最初の1本目では使いません。

RUN — 1行ごとにレイヤーができる

RUN を3行書くと、レイヤーが3枚できます。目で見ます。

FROM node:22-slim

WORKDIR /app
RUN apt-get update
RUN apt-get install -y --no-install-recommends ca-certificates
RUN rm -rf /var/lib/apt/lists/*
bash
$ docker build -t dockerlab:v4bad .
$ docker image ls dockerlab
REPOSITORY   TAG      IMAGE ID       CREATED         SIZE
dockerlab    v4bad    3f8a9b2c1d0e   5 seconds ago   264MB

225MB だったものが 264MB になりました。 ここで問題は、最後の行で消したはずのものが、消えていないことです。

bash
$ docker history dockerlab:v4bad
IMAGE          CREATED         CREATED BY                                      SIZE
3f8a9b2c1d0e   5 seconds ago   RUN /bin/sh -c rm -rf /var/lib/apt/lists/* #…   0B
<missing>      5 seconds ago   RUN /bin/sh -c apt-get install -y --no-inst…   1.2MB
<missing>      6 seconds ago   RUN /bin/sh -c apt-get update # buildkit        38.2MB
<missing>      6 seconds ago   WORKDIR /app                                    0B
<missing>      2 weeks ago     /bin/sh -c #(nop)  CMD ["node"]                 0B
...

apt-get update の行が 38.2MB 増やしていて、rm -rf の行は 0B です。

これがレイヤーの本質です。

レイヤーは差分の積み重ねで、下の層は書き換わりません。 後の行で消しても、「消えたという記録」が上に乗るだけで、下の層の実体は残ったままです。

だから && で繋ぎます。 「入れて、消す」が1枚のレイヤーの中で完結すれば、そもそも増えた分が保存されません。

FROM node:22-slim

WORKDIR /app
RUN apt-get update \
 && apt-get install -y --no-install-recommends ca-certificates \
 && rm -rf /var/lib/apt/lists/*
bash
$ docker build -t dockerlab:v4 .
$ docker image ls dockerlab
REPOSITORY   TAG      IMAGE ID       CREATED          SIZE
dockerlab    v4       7c1d0e3f8a9b   4 seconds ago    226MB
dockerlab    v4bad    3f8a9b2c1d0e   2 minutes ago    264MB

264MB → 226MB。 やっていることは同じで、書き方だけが違います。

&& で繋ぐ理由はもう1つあります。

bash
$ RUN apt-get update; apt-get install -y foo

; で繋ぐと、前が失敗しても次が走ります。 apt-get update が失敗したのに install に進み、古い索引で入れてしまうことになります。&& は「前が成功したときだけ次へ」なので、失敗が失敗のまま止まります。

\ は行の続きを表します。 行末に \ を置くと次の行と繋がって1行として扱われます。\ の後ろに空白があると効かないので、貼り付けるときは注意してください。

分けるべき RUN もある

「全部 && で1行にすればいい」ではありません。 レイヤーはキャッシュの単位でもあるからです。

状況どうするか
入れて消すのがセットの処理1つの RUN にまとめる(残骸を残さない)
変わりにくいもの(依存のインストール)前のほうに置いて、独立した行にする(キャッシュを効かせる)
変わりやすいもの(自分のソース)後ろに置く

この並べ方が、この後の「キャッシュ」の話に直結します。

ENV と ARG — ビルド時と実行時

似ていますが、生きている時間が違います。

いつ使えるイメージに残るか
ARGビルド中だけ変数としては残らない(が、後述のとおり履歴には残る)
ENVビルド中と、実行中の両方残る。docker inspect で見える

実際に確かめます。

FROM node:22-slim

ARG BUILD_NOTE=built-by-hand
ENV GREETING=hello-from-env

WORKDIR /app
RUN echo "ARG は今 [$BUILD_NOTE]、ENV は今 [$GREETING]"
bash
$ docker build -t dockerlab:v5 .
 => [3/3] RUN echo "ARG は今 [built-by-hand]、ENV は今 [hello-from-env]"

ビルド中は、どちらも読めています。 では実行時はどうか。

bash
$ docker run --rm dockerlab:v5 env
PATH=/usr/local/sbin:...
HOSTNAME=8f1a2b3c4d5e
NODE_VERSION=22.20.0
GREETING=hello-from-env
HOME=/root

GREETING はありますが、BUILD_NOTE はありません。 ARG はビルドが終わった時点で消えます。

ビルド時に値を渡すのは --build-arg です。

bash
$ docker build --build-arg BUILD_NOTE=from-command-line -t dockerlab:v5 .
 => [3/3] RUN echo "ARG は今 [from-command-line]、ENV は今 [hello-from-env]"

実行時に ENV を上書きするのは -e です。

bash
$ docker run --rm -e GREETING=overwritten dockerlab:v5 env | grep GREETING
GREETING=overwritten

まとめるとこうです。

ARG は --build-arg で渡し、ビルドが終わると消える。ENV は -e で上書きでき、消えない。

ARG に秘密情報を渡すと、イメージに残る

ここは事故の話です。 「ENV に書くと docker inspect で見えてしまうから、ARG で渡せば安全」という書き方を、よく見かけます。安全ではありません。

FROM node:22-slim

ARG API_TOKEN
RUN echo "取得に使いました: ${#API_TOKEN}文字" > /tmp/build.log
bash
$ docker build --build-arg API_TOKEN=super-secret-value -t dockerlab:leak .

ビルド自体は何ごともなく通ります。では、履歴を見ます。

bash
$ docker history --no-trunc dockerlab:leak | head -3
IMAGE   CREATED         CREATED BY
sha256:...   8 seconds ago   |1 API_TOKEN=super-secret-value /bin/sh -c echo "取得に使いました: ${#API_TOKEN}文字" > /tmp/build.log

API_TOKEN=super-secret-value が、そのまま残っています。

イメージの履歴は、イメージと一緒に配られます。 レジストリに push すれば、pull できる全員がこれを読めます。 アプリのコードに書いていなくても、.env に入れていなくても、ここに出ます。

正しい渡し方は --mount=type=secret です。

# syntax=docker/dockerfile:1
FROM node:22-slim

RUN --mount=type=secret,id=api_token \
    echo "先頭4文字だけ確認: $(head -c 4 /run/secrets/api_token)"
bash
$ echo -n "super-secret-value" > token.txt
$ docker build --secret id=api_token,src=token.txt -t dockerlab:secret .
 => [2/2] RUN --mount=type=secret,id=api_token echo "先頭4文字だけ確認: $(...)"
#6 0.191 先頭4文字だけ確認: supe
bash
$ docker history --no-trunc dockerlab:secret | head -3
IMAGE        CREATED         CREATED BY
sha256:...   6 seconds ago   RUN /bin/sh -c echo "先頭4文字だけ確認: $(head -c 4 /run/secrets/api_token)" # buildkit

値が出ていません。 シークレットはその RUN の実行中だけ /run/secrets/ に現れて、レイヤーには保存されません。

1行目の # syntax=docker/dockerfile:1 はコメントに見えますが、機能します。 BuildKit に「新しい書式の機能を使う」と伝える行です。--mount=type=secret を使うなら必要です。 秘密の扱いそのものは.envは暗号化してGitに置ける — SOPSとageで扱っています。

bash
$ rm -f token.txt
$ docker image rm dockerlab:leak dockerlab:secret

EXPOSE — これはドキュメントであって、ポートは開かない

冒頭で挙げた「EXPOSE 8080 と書いたのに繋がらない」の答えです。

FROM node:22-slim

WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY server.js ./

EXPOSE 3000

CMD ["node", "server.js"]
bash
$ docker build -t dockerlab:v6 .
$ docker run -d --name lab6 dockerlab:v6
$ docker ps
CONTAINER ID   IMAGE          COMMAND            STATUS         PORTS      NAMES
a1b2c3d4e5f6   dockerlab:v6   "node server.js"   Up 3 seconds   3000/tcp   lab6

PORTS に 3000/tcp と出ています。 開いているように見えます。繋いでみます。

bash
$ curl http://localhost:3000/
curl: (7) Failed to connect to localhost port 3000 after 0 ms: Connection refused

繋がりません。 EXPOSE は何も開いていないからです。

EXPOSE がやっていることは、これだけです。

「このイメージは 3000 番で待つつもりです」というメモを、イメージのメタデータに書く。

読むのは人間と、道具です。

誰が読むかどう使うか
人間Dockerfile を見て「何番で待つのか」が分かる
docker run -P(大文字)EXPOSE されている全ポートを、空いている番号に自動で繋ぐ
docker ps の表示3000/tcp と出る(繋がっているという意味ではない)
Compose や他のツール参考情報として読む

実際に外から繋ぐのは -p(小文字)です。

bash
$ docker rm -f lab6
$ docker run -d --name lab6 -p 3000:3000 dockerlab:v6
$ curl http://localhost:3000/
hello from dockerlab

繋がりました。

確認として、EXPOSE を消しても -p は効きます。 逆に EXPOSE があっても -p が無ければ繋がりません。この2つは独立しています。

docker ps の PORTS 欄の読み分けは覚えておくと得です。 3000/tcp = EXPOSE されているだけ。0.0.0.0:3000->3000/tcp = 本当に繋がっている。 矢印があるかどうかが分かれ目です。

[スクリーンショット: 02_expose_refused.png] EXPOSE 3000 だけで起動したコンテナに curl http://localhost:3000/ を打って Connection refused が返り、その後 -p 3000:3000 を付けると hello from dockerlab が返る、という2つを1画面で撮ってください。

CMD と ENTRYPOINT — 4通りの組み合わせ

「起動時に何を実行するか」を決める命令が2つあります。 役割が違います。

役割docker run image 引数 を付けたとき
CMD既定のコマンド、または既定の引数丸ごと差し替えられる
ENTRYPOINT必ず実行される本体差し替わらない(引数として後ろに付く)

組み合わせは4通りです。 どれも実際に起きます。

#ENTRYPOINTCMD実際に走るもの
①なし["node","server.js"]node server.js。docker run image ls と打つと ls に置き換わる
②["node","server.js"]なしnode server.js。docker run image ls と打つと node server.js ls になる
③["node"]["server.js"]node server.js。docker run image other.js で node other.js(CMD が既定の引数)
④shell形式 node server.js何を書いても/bin/sh -c "node server.js"。CMD は無視される

③ が「ENTRYPOINT + CMD」の本来の使い方です。 「本体は固定、引数だけ差し替えたい」ときの形です。

実際に ③ を確かめます。

FROM node:22-slim

WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY server.js ./

EXPOSE 3000

ENTRYPOINT ["node"]
CMD ["server.js"]
bash
$ docker build -t dockerlab:v7 .
$ docker run --rm dockerlab:v7 --version
v22.20.0

server.js が --version に差し替わり、node --version が走りました。 node の部分は差し替わっていません。

④ は事故です。 次の節がその話です。

exec形式と shell形式

同じことを書いているように見えて、走るものが違います。

書き方実際に起動するもの
exec形式 CMD ["node", "server.js"]node が直接起動する。PID 1 は node
shell形式 CMD node server.js/bin/sh -c "node server.js" が起動する。PID 1 は sh

見比べます。

bash
$ docker run -d --name lab-exec -p 3000:3000 dockerlab:v6
$ docker exec lab-exec ps -eo pid,comm
    PID COMMAND
      1 node
     15 ps

PID 1 が node です。 shell形式で作り直します。

bash
$ nano Dockerfile
FROM node:22-slim

WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY server.js ./

EXPOSE 3000

CMD node server.js
bash
$ docker build -t dockerlab:v8shell .
$ docker run -d --name lab-shell -p 3001:3000 dockerlab:v8shell
$ docker exec lab-shell ps -eo pid,comm
    PID COMMAND
      1 sh
      7 node
     18 ps

PID 1 が sh になり、node は子プロセスの 7 番になりました。 ここから問題が起きます。

shell形式だと docker stop で10秒待たされる(実際に測る)

docker stop は、こういう順番で動きます。

  1. PID 1 に SIGTERM(丁寧な終了要求)を送る
  2. 既定で10秒待つ
  3. まだ生きていたら SIGKILL(強制終了)

exec形式のほうを測ります。

bash
$ time docker stop lab-exec
lab-exec

real	0m0.412s
user	0m0.019s
sys	0m0.012s

0.4秒で止まりました。 node が PID 1 なので、SIGTERM が直接届き、server.js の process.on('SIGTERM', …) で自分で終了しています。 PID 1 のプロセスは、ハンドラを書いていないシグナルが無視されます。 この1行が無いと、exec形式でも10秒待たされます。

shell形式のほうを測ります。

bash
$ time docker stop lab-shell
lab-shell

real	0m10.348s
user	0m0.021s
sys	0m0.014s

10.3秒。 きっかり10秒待たされてから、強制終了されています。

理由はこうです。

SIGTERM は PID 1 の sh に届きます。ところが sh -c は、受け取ったシグナルを子プロセスに転送しません。 sh は「自分は何もしないで待っているだけ」なので、node は何も知らないまま動き続け、10秒後に SIGKILL で叩き落とされます。

これが「毎回10秒止まらない」の正体でした。 そして本当に困るのは、待たされることではありません。

  • SIGKILL は捕まえられません。 アプリは後片づけを一切できずに殺されます
  • 処理中のリクエストは途中で切れます
  • デプロイのたびにこれが起きます。 コンテナは頻繁に作り直すものなので、毎回です

対処は、exec形式で書くことです。 そのうえで、PID 1 になった node が SIGTERM を受け取れるように、server.js の process.on('SIGTERM', …) を書いておくか、docker run --init を付けます。

CMD ["node", "server.js"]

配列で書く。それだけです。

CMD ["npm", "start"] も同じ問題を起こします。 配列にしても、npm が node を子プロセスとして起動するので、PID 1 は npm になるからです。npm start をコンテナの起動コマンドにしない、と覚えてください。 どうしても子プロセス構成になる場合は、docker run --init を付けるか、tini のような小さな初期プロセスを入れて、シグナルを転送させます。

片づけておきます。

bash
$ docker rm -f lab-exec lab-shell lab6
$ docker image rm dockerlab:v8shell

[スクリーンショット: 03_stop_10sec.png] time docker stop を exec形式と shell形式の2つに対して打ち、real 0m0.4s と real 0m10.3s が並んで見える画面を撮ってください。

.dockerignore — 書かないと node_modules と .env が入る

docker build . の . は、「このフォルダを丸ごと Docker に送る」という意味でした。 いま ~/dockerlab には何が入っているか。

bash
$ cd ~/dockerlab
$ du -sh .
$ ls -a
2.4M	.
.  ..  .env  Dockerfile  node_modules  package-lock.json  package.json  sample  sample.tar.gz  server.js

.env と node_modules も、丸ごと送られています。

Dockerfile を、よく見る形(COPY . .)に戻して確かめます。

bash
$ nano Dockerfile
FROM node:22-slim

WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY . .

EXPOSE 3000

CMD ["node", "server.js"]
bash
$ docker build --progress=plain --no-cache -t dockerlab:v9 . 2>&1 | grep -i "transferring context"
#2 [internal] load build context
#2 transferring context: 2.36MB 0.1s done

2.36MB が送られました。 イメージの中身を見ます。

bash
$ docker run --rm dockerlab:v9 ls -a /app
.
..
.env
Dockerfile
node_modules
package-lock.json
package.json
sample
sample.tar.gz
server.js

.env が入っています。 さっき置いたダミーの秘密が、そのままイメージに焼き込まれました。

bash
$ docker run --rm dockerlab:v9 cat /app/.env
SECRET_TOKEN=do-not-ship-me

読めます。 これを push すれば、pull できる人全員が読めます。

.dockerignore を書く

bash
$ nano .dockerignore

このファイルの全文です。

node_modules
npm-debug.log
.env
.env.*
.git
.gitignore
Dockerfile
.dockerignore
sample
sample.tar.gz

もう一度、同じコマンドで測ります。

bash
$ docker build --progress=plain --no-cache -t dockerlab:v9 . 2>&1 | grep -i "transferring context"
#2 [internal] load build context
#2 transferring context: 3.42kB 0.0s done

2.36MB → 3.42kB。 700倍近く減りました。

bash
$ docker run --rm dockerlab:v9 ls -a /app
.
..
node_modules
package-lock.json
package.json
server.js

.env も sample.tar.gz も入っていません。 node_modules はイメージの中に残っていますが、これは手元から送られたものではなく、RUN npm ci がコンテナの中で作ったものです。

昔の記事に出てくる Sending build context to Docker daemon 2.36MB は、いまは transferring context: 2.36MB と表示されます。 呼び方が変わっただけで、指しているものは同じです。BuildKit が既定になったためです。

書き方の要点です。

書き方意味
node_modulesどの階層にあっても除外される
*.logワイルドカードが使える
.env.*.env.local などをまとめて除外
!keep.txt! は除外の取り消し。前の行で除外したものを戻す

node_modules を除外する理由は、サイズだけではありません。

手元の node_modules は「この VM で入れたもの」です。 ネイティブモジュールを含む場合、手元の OS 向けにビルドされたバイナリが入っています。それをコンテナに持ち込むと、コンテナの中では動きません。 コンテナの中で npm ci を回す形にしておけば、その環境向けのものが入ります。

.dockerignore は必ず Dockerfile と同じ場所に置きます。 サブフォルダに置いても読まれません。

ビルドの中身を見る — –progress=plain とキャッシュ

「ソースを1文字直しただけなのに npm install が最初から走る」を潰します。

いまの Dockerfile は、こういう順番でした。

COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY . .

server.js を1文字だけ変えて、もう一度ビルドします。

bash
$ sed -i "s/hello from dockerlab/hello from dockerlab v2/" server.js
$ docker build --progress=plain -t dockerlab:v9 . 2>&1 | grep -E "^#[0-9]+ \[|CACHED|DONE"
#5 [1/5] FROM docker.io/library/node:22-slim
#5 CACHED
#6 [2/5] WORKDIR /app
#6 CACHED
#7 [3/5] COPY package.json package-lock.json ./
#7 CACHED
#8 [4/5] RUN npm ci --omit=dev
#8 CACHED
#9 [5/5] COPY . .
#9 DONE 0.1s

npm ci は CACHED です。走っていません。 走ったのは最後の COPY . . だけです。

--progress=plain を付ける理由は、ここにあります。 付けないと、BuildKit は行を上書きしながら進捗を表示するので、終わったあとに何が起きたのか読み返せません。 plain を付けると、1行ずつ順に流れて残ります。

キャッシュの判定ルールは、驚くほど単純です。

上から順に見て、「その行の内容」と「その行が持ち込むファイルの中身」が前回と同じなら、キャッシュを使う。 1行でも違ったら、その行から下は全部やり直す。

だから順番が全部です。

順番何が起きるか
COPY . . → RUN npm ciソースを1文字直すと COPY が変わる → 下の npm ci も毎回やり直し
COPY package.json → RUN npm ci → COPY . .依存が変わらないかぎり npm ci はキャッシュ。ソースの変更は最後の行だけ

わざと壊して確かめます。 package.json を触ります。

bash
$ sed -i 's/"version": "1.0.0"/"version": "1.0.1"/' package.json
$ docker build --progress=plain -t dockerlab:v9 . 2>&1 | grep -E "^#[0-9]+ \[|CACHED|DONE" | head -12
#5 [1/5] FROM docker.io/library/node:22-slim
#5 CACHED
#6 [2/5] WORKDIR /app
#6 CACHED
#7 [3/5] COPY package.json package-lock.json ./
#7 DONE 0.0s
#8 [4/5] RUN npm ci --omit=dev
#8 6.842 added 65 packages in 6s
#8 DONE 7.1s

COPY package.json が変わった瞬間に、下の npm ci もキャッシュを失いました。 これが「1行変わったら下は全部」の意味です。

キャッシュを完全に無視したいときは --no-cache です。 「キャッシュのせいで古いものを掴んでいる気がする」ときの切り分けに使います。

bash
$ docker build --no-cache -t dockerlab:v9 .

docker history — どの行が何MB増やしたか

イメージが大きい」ときに、どの行が原因かを1コマンドで出せます。

bash
$ docker history dockerlab:v9
IMAGE          CREATED          CREATED BY                                      SIZE
b4c5d6e7f8a9   2 minutes ago    CMD ["node" "server.js"]                        0B
<missing>      2 minutes ago    EXPOSE map[3000/tcp:{}]                         0B
<missing>      2 minutes ago    COPY . . # buildkit                             3.4kB
<missing>      2 minutes ago    RUN /bin/sh -c npm ci --omit=dev # buildkit     2.29MB
<missing>      2 minutes ago    COPY package.json package-lock.json ./ # buil…  33.7kB
<missing>      2 minutes ago    WORKDIR /app                                    0B
<missing>      2 weeks ago      /bin/sh -c #(nop)  CMD ["node"]                 0B
<missing>      2 weeks ago      /bin/sh -c #(nop)  ENTRYPOINT ["docker-entryp…  0B
<missing>      2 weeks ago      /bin/sh -c set -ex && for key in ...            5.4MB
<missing>      2 weeks ago      /bin/sh -c #(nop)  ENV YARN_VERSION=1.22.22     0B
<missing>      2 weeks ago      /bin/sh -c ARCH= && dpkgArch="$(dpkg --print-…  184MB
<missing>      2 weeks ago      /bin/sh -c #(nop)  ENV NODE_VERSION=22.20.0     0B
<missing>      2 weeks ago      /bin/sh -c groupadd --gid 1000 node && useradd…  345kB
<missing>      2 weeks ago      /bin/sh -c #(nop) ADD file:... in /             80.5MB

読み方は3つです。

見るもの分かること
SIZE の大きい行どの命令が容量を食っているか。ここでは node 本体の 184MB と、土台の Debian の 80.5MB
<missing> の行ローカルにビルド記録が無い層。エラーではない。pull してきたイメージの層はこう出る
自分が書いた行上から数行。RUN npm ci が 2.29MB、COPY . . が 3.4kB

0B の行は、ファイルを1バイトも増やしていません。 CMD EXPOSE WORKDIR ENV はメタデータを書いているだけなので、レイヤーとしては空です。

自分の書いた5行で増えたのは 2.3MB ほど、残り 223MB は土台です。 「イメージが重い」と言うときの重さは、たいてい土台の選び方の話になります。

bash
$ docker image ls dockerlab:v9
REPOSITORY   TAG   IMAGE ID       CREATED         SIZE
dockerlab    v9    b4c5d6e7f8a9   3 minutes ago   228MB

docker history の SIZE を全部足しても、docker image ls の SIZE とはぴったり一致しません。 共有されている層があるためです。「どの行が重いか」を比べる道具として使ってください。

HEALTHCHECK — 「動いている」と「応えている」は別

コンテナが Up でも、中のアプリが応えているとは限りません。 プロセスは生きているのに、データベースへの接続を失って全リクエストが失敗している、という状態は普通に起きます。HEALTHCHECK は、その差を埋めます。

server.js に置いた /healthz を使います。

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD node -e "fetch('http://127.0.0.1:3000/healthz').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
オプション意味
--interval何秒ごとに調べるか
--timeout何秒で返らなかったら失敗とみなすか
--start-period起動直後の猶予。この間の失敗は回数に数えない
--retries何回続けて失敗したら unhealthy にするか

curl を使わない理由は、node:22-slim に curl が入っていないからです。そのためだけに apt-get install curl を足すと、イメージが数MB増えます。 Node.js 22 には fetch が最初からあるので、node -e で済ませます。

結果は docker ps の STATUS に出ます。

bash
$ docker run -d --name lab-health -p 3000:3000 dockerlab:v10
$ docker ps --format "table {{.Names}}\t{{.Status}}"
NAMES         STATUS
lab-health    Up 8 seconds (health: starting)

しばらく待つと Up 45 seconds (healthy) に変わります。失敗が続けば (unhealthy) です。

Compose 側にも同じ設定があります。 本線のComposeの回で depends_on が待ってくれない話を書きましたが、待たせるための材料がこれです。

services:
  app:
    build: .
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/healthz').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
      interval: 10s
      timeout: 3s
      retries: 3

どちらに書くかの考え方はこうです。

アプリ自身の生存確認は Dockerfile に書く(イメージを配ればどこでも効く)。運用の都合で間隔を変えたいときは Compose 側で上書きする(Compose の healthcheck が Dockerfile の HEALTHCHECK に優先する)。

なお unhealthy になっても、Docker は勝手に再起動しません。 再起動させたいなら --restart や、Compose の depends_on: condition: service_healthy と組み合わせます。「印が付くだけ」であることは押さえてください。

USER — 既定は root。本番では落とす

Dockerfile に USER を書かないと、コンテナの中のプロセスは root として動きます。

bash
$ docker run --rm dockerlab:v9 id
uid=0(root) gid=0(root) groups=0(root)

uid が 0、つまり root です。 「コンテナだから隔離されている」というのは、そこまで強い保証ではありません。 ボリュームでホストのフォルダをマウントしていれば、そのフォルダには root として書き込めます。 脆弱性でコンテナから抜け出す経路が見つかったときの被害も、root かどうかで大きく変わります。

node 公式イメージには、最初から node という一般ユーザー(uid 1000)が入っています。 使わせてもらいます。

COPY --chown=node:node package.json package-lock.json ./
RUN npm ci --omit=dev
COPY --chown=node:node server.js ./

USER node
CMD ["node", "server.js"]
bash
$ docker run --rm dockerlab:v10 id
uid=1000(node) gid=1000(node) groups=1000(node)

3つ、順番の注意があります。

  1. USER は、それ以降の RUN CMD ENTRYPOINT に効きます。 apt-get install のような root が要る処理は、USER より前に書きます
  2. ファイルの持ち主を合わせます。 root が置いたファイルは node から書けません。COPY --chown=node:node で、置くときに持ち主を決めます(rwx と所有者の話は本線のPermission denied の正体にあります)
  3. 1024番未満のポートは、一般ユーザーでは待ち受けられない環境があります。 いまの Docker(20.10 以降の通常の構成)はコンテナの中では許可していますが、rootless の Docker やほかの実行環境では制限が残り、80番で待つ設計だと USER を入れた瞬間に落ちます。このアプリを 3000番にしてあるのは、そのためです

USER に書くのは名前でも uid でもかまいませんが、uid のほうが確実です(USER 1000)。イメージによっては、その名前のユーザーが存在しないことがあるためです。

完成した Dockerfile

ここまでの全部を1本にまとめます。

bash
$ nano Dockerfile

このファイルの全文です。

# syntax=docker/dockerfile:1
FROM node:22-slim

ENV NODE_ENV=production
ENV PORT=3000

WORKDIR /app

COPY --chown=node:node package.json package-lock.json ./
RUN npm ci --omit=dev && npm cache clean --force

COPY --chown=node:node server.js ./

EXPOSE 3000

USER node

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD node -e "fetch('http://127.0.0.1:3000/healthz').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"

CMD ["node", "server.js"]

1行ずつ、なぜそう書いたか。

行理由
# syntax=docker/dockerfile:1BuildKit の新しい書式を使う宣言。コメントに見えるが機能する
FROM node:22-slimタグを明示。latest は固定されない。slim はビルド用の道具を含まない
ENV NODE_ENV=production実行時にも残る。多くのライブラリがこれを見て挙動を変える
WORKDIR /appRUN cd は次の行に効かない。無ければ作られる
COPY package.json ... → RUN npm ci変わりにくいものを先に。ソースを直しても npm ci はキャッシュされる
--chown=node:node後で USER node にするので、置くときに持ち主を合わせる
&& npm cache clean --force同じ RUN の中で消す。行を分けると消えない
COPY server.js ./変わりやすいものを後に。COPY . . にしないのは、送るものを明示するため
EXPOSE 3000ポートは開かない。メモ。開くのは -p
USER node既定は root。root が要る処理より後に置く
HEALTHCHECKUp と「応えている」は別。curl を入れずに node -e で済ませる
CMD ["node", ...]exec形式。shell形式だと docker stop に10秒かかる

ビルドして、最後の確認をします。

bash
$ docker build -t dockerlab:v10 .
$ docker run -d --name lab-final -p 3000:3000 dockerlab:v10
$ curl http://localhost:3000/
hello from dockerlab v2
bash
$ docker exec lab-final ps -eo pid,comm
$ docker exec lab-final id
$ time docker stop lab-final
    PID COMMAND
      1 node
     14 ps
uid=1000(node) gid=1000(node) groups=1000(node)
lab-final

real	0m0.398s
user	0m0.018s
sys	0m0.011s

PID 1 が node、実行ユーザーが node、停止が0.4秒。 冒頭の3つの症状が、全部消えました。

[スクリーンショット: 04_final_check.png] docker exec lab-final ps -eo pid,comm と id、time docker stop lab-final の結果が並んでいる画面を撮ってください。

書き終えたら hadolint で検査する

Dockerfile 専用の検査ツールがあります。 hadolint です。Docker で動かせるので、VM に何も入れずに使えます。

bash
$ docker run --rm -i hadolint/hadolint < Dockerfile

何も出なければ、指摘ゼロです。 出るとこうなります。試しに、途中で作った apt-get 入りの Dockerfile を検査してみます。

bash
$ cat > /tmp/Dockerfile.bad <<'EOF'
  FROM node
  RUN apt-get update
  RUN apt-get install -y curl
  ADD . /app
  CMD npm start
  EOF
$ docker run --rm -i hadolint/hadolint < /tmp/Dockerfile.bad
-:1 DL3006 warning: Always tag the version of an image explicitly
-:2 DL3009 info: Delete the apt-get lists after installing something
-:3 DL3008 warning: Pin versions in apt get install. Instead of `apt-get install <package>` use `apt-get install <package>=<version>`
-:3 DL3009 info: Delete the apt-get lists after installing something
-:3 DL3015 info: Avoid additional packages by specifying `--no-install-recommends`
-:4 DL3020 error: Use COPY instead of ADD for files and folders
-:5 DL3025 warning: Use arguments JSON notation for CMD and ENTRYPOINT arguments

この記事で書いてきたことが、ほぼそのまま並んでいます。

コード指摘この記事のどこ
DL3006タグを明示せよ「latest は固定ではない」
DL3009apt-get の索引を消せ「1行ごとにレイヤーができる」
DL3008パッケージの版を固定せよ同上(再現性の話)
DL3015--no-install-recommends を付けよ同上
DL3020ADD ではなく COPY「COPY と ADD」
DL3025CMD は JSON の形(exec形式)で書け「exec形式と shell形式」

深刻度は3段階です。 error / warning / info。info を全部潰す必要はありませんが、error は直します。

特定の指摘を無視したいときは、その行の直前にコメントで書きます。

# hadolint ignore=DL3008
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates \
 && rm -rf /var/lib/apt/lists/*

無視する理由をコメントで隣に書いておいてください。 半年後に見て「なぜ無視しているのか」が分からないと、外していいのか判断できません。

.dockerignore に Dockerfile を入れているので、検査対象のファイル自体はイメージに入りません。検査はビルドの外側の作業です。

つまずいたところ

① EXPOSE を消したら動かなくなると思い込んでいた

「メモに過ぎない」と読んでも、消す勇気が出ませんでした。実際に消してビルドし、-p 3000:3000 で普通に繋がるのを見て、やっと納得しました。 逆に EXPOSE を残したまま -p を消すと、docker ps には 3000/tcp と出るのに繋がりません。この「出ているのに繋がらない」表示が、いちばん誤解させます。

② RUN cd /app が効いていないことに、しばらく気づかなかった

エラーが出ないからです。COPY . . の行き先がずれていて、「ファイルを入れたはずなのに MODULE_NOT_FOUND」という、原因から遠いエラーだけを見ていました。RUN pwd を1行挟むだけで一発で分かると気づくのに、30分かかりました。

③ docker stop の10秒を「Docker が遅い」と思っていた

「コンテナは起動が速い」と聞いていたのに、止めるのが遅い。Docker の仕様だと諦めていました。 docker exec ... ps で PID 1 が sh だと分かった瞬間に繋がりましたが、「シグナルが届いていない」という発想自体が無かったのが原因です。プロセスとシグナルの話は本線のstartとenableは別物で触れていたのに、コンテナと結びつけていませんでした。

④ npm install と npm ci を取り違えた

最初 RUN npm install と書いていて、package-lock.json がコンテナの中で書き換わっていました。手元のロックファイルと中身が食い違い、「手元では動くのにコンテナでは動かない」が起きます。npm ci はロックファイルどおりにしか入れず、食い違えばエラーで止まります。 ビルドでは ci を使います(node_modulesは消してよいに install と ci の違いを書きました)。

⑤ .dockerignore をサブフォルダに置いて、効かなかった

src/.dockerignore に書いて「除外されない」と悩みました。.dockerignore は、docker build に渡したコンテキストの直下(= Dockerfile と同じ場所)にしか置けません。

⑥ --build-arg で渡したトークンが漏れることを、この記事を書くまで知らなかった

「ENV は inspect で見えるから ARG にしよう」と考えていました。docker history --no-trunc を打って、値がそのまま出ているのを見て青くなりました。 練習用のダミーだったので実害はありませんでしたが、本番の鍵でやっていたら push した時点で終わりです。

後片づけ

この記事で作ったものを全部消します。 既存の ~/server や ~/hitokoto には触れていないので、そちらはそのまま残ります。

コンテナを止めて消す

bash
$ docker ps -a --filter "name=lab" --format "table {{.Names}}\t{{.Status}}"
NAMES         STATUS
lab-health    Exited (137) 5 minutes ago
lab-final     Exited (0) 2 minutes ago
bash
$ docker rm -f lab-health lab-final lab-exec lab-shell lab6 2>/dev/null
$ docker ps -a --filter "name=lab"

確認: 見出し行だけが返れば、全部消えています。No such container のエラーは、すでに消えている分なので気にしなくて構いません。

イメージを消す

bash
$ docker image ls dockerlab
REPOSITORY   TAG      TAG           IMAGE ID       SIZE
dockerlab    v10      b4c5d6e7f8a9  228MB
dockerlab    v9       ...           228MB
dockerlab    v7       ...           228MB
...

練習で作ったタグが全部残っています。 まとめて消します。

bash
$ docker image rm $(docker image ls dockerlab -q) 2>/dev/null
$ docker image ls dockerlab

確認: 見出し行だけになれば消えています。

検査に使ったイメージと、latest の実験で引いたイメージも消します。

bash
$ docker image rm hadolint/hadolint alpine:latest alpine:3.20

node:22-slim は残しておいて構いません。 次に使うときに、また 225MB 引くことになります。消したい場合だけ docker image rm node:22-slim です。

ビルドキャッシュを見る(消すかどうかは選ぶ)

docker image rm では、ビルドキャッシュは消えません。 どれだけ溜まっているか見ます。

bash
$ docker system df
TYPE            TOTAL   ACTIVE   SIZE      RECLAIMABLE
Images          1       0        225MB     225MB (100%)
Containers      0       0        0B        0B
Local Volumes   0       0        0B        0B
Build Cache     18      0        41.2MB    41.2MB

Build Cache の 41.2MB が、練習の残りです。 消すならこうです。

bash
$ docker builder prune
WARNING! This will remove all dangling build cache. Are you sure you want to continue? [y/N] y
Total reclaimed space: 41.2MB

docker system prune -a は打たないでください。 止まっているコンテナと、使っていないイメージを全部消します。他の練習で作ったものまで巻き込みます。

練習用フォルダを消す

bash
$ cd ~
$ rm -rf ~/dockerlab
$ ls ~

確認: dockerlab が消え、server や hitokoto がそのまま残っていることを確認してください。

bash
$ rm -f /tmp/Dockerfile.bad

まとめ

  • 他人の Dockerfile が動いても、1行ずつ確かめないと同じ症状を持ち込む。 冒頭の3つ(繋がらない・10秒待つ・毎回 npm install)は全部この Dockerfile の書き方が原因だった
  • FROM でタグを省くと latest。latest は「最新」を保証する仕組みではなく、いつでも差し替わるただのタグ名。 node:22-slim のように明示する。完全に固定したいなら @sha256: のダイジェスト
  • slim はビルド用の道具が入っていない版。 node:22 は 1.1GB、node:22-slim は 225MB
  • RUN cd /app は次の行に効かない。 RUN は1行ごとに別のコンテナで走り、残るのはファイルの差分だけだから。ディレクトリを移すのは WORKDIR
  • WORKDIR は移動・作成・相対パスの基準を同時にやる。 先に RUN mkdir は要らない
  • ADD は tar を勝手に展開し、URL からダウンロードもする。 便利ではなく驚きが多い。COPY を使い、展開したいなら RUN tar と書く
  • RUN は1行ごとにレイヤーができる。 後の行で rm しても下の層の実体は消えない。apt-get update と install と rm -rf は1つの RUN に && で繋ぐ
  • ; ではなく &&。 ; は前が失敗しても次に進む
  • ARG はビルド時だけ、ENV は実行時にも残る。 --build-arg と -e で渡す
  • ARG に秘密を渡すと docker history --no-trunc に値がそのまま出る。 「ENV は見えるから ARG に」は間違い。RUN --mount=type=secret と --secret を使う
  • EXPOSE はポートを開かない。 メタデータに書くだけ。開くのは -p。docker ps の PORTS は、矢印(->)があって初めて繋がっている
  • CMD は差し替えられる既定値、ENTRYPOINT は差し替えられない本体。 「本体固定・引数だけ差し替え」なら ENTRYPOINT + CMD の組み合わせ
  • shell形式(CMD node server.js)だと PID 1 が sh になり、docker stop の SIGTERM が node に届かない。 10秒待って SIGKILL。実測 0.4秒 対 10.3秒
  • SIGKILL は捕まえられない。 待たされるより、後片づけができずに殺されることが問題
  • CMD ["npm", "start"] も同じ問題を起こす。 配列でも npm が PID 1 になる。起動コマンドに npm を挟まない
  • .dockerignore が無いと node_modules も .env も送られ、COPY . . でイメージに入る。 実測 2.36MB → 3.42kB
  • .dockerignore は Dockerfile と同じ場所にしか置けない。 サブフォルダは読まれない
  • 手元の node_modules は持ち込まない。 その OS 向けにビルドされたものが混ざる。コンテナの中で npm ci を回す
  • キャッシュは「上から順に、内容が同じなら使う。1行違ったら下は全部やり直し」。 だから変わりにくいものを先、変わりやすいものを後に置く
  • --progress=plain を付けると、どの行が CACHED でどの行が走ったかが残る。 付けないと上書きされて読み返せない
  • docker history で、どの行が何MB増やしたかが分かる。 0B の行はメタデータだけ。<missing> はエラーではなく、pull してきた層
  • HEALTHCHECK は Up と「応えている」を区別する。 ただし印が付くだけで、勝手に再起動はしない。Compose 側の healthcheck が優先する
  • USER を書かないと root で動く。 node イメージには uid 1000 の node がいる。COPY --chown で持ち主を合わせ、1024番未満のポートは使わない
  • 書き終えたら docker run --rm -i hadolint/hadolint < Dockerfile。 指摘の中身は、この記事でやってきたことと同じ。error は直し、無視するならコメントで理由を残す

参考リンク


次に読む

この記事は 【深掘り】Docker の 2 / 11 本目です。

記事
← 前の記事コンテナとVMの違いを測る — 軽いのはOSを起動しないから
→ 次の記事レイヤーキャッシュの仕組み — 行の順番でビルド時間が決まる

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

DevOps›Docker — Dockerfiles
  • FROM / COPY / RUN / CMD / ENTRYPOINT を1行ずつ
  • .dockerignore と HEALTHCHECK

この記事は、上の項目を実際に手を動かして確かめる回です。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次