Dockerでの開発ワークフロー — bind mountでnode_modulesが消える

Dockerでの開発ワークフロー。コードを書くパソコンとコンテナ、フォルダと虫眼鏡。

bind mountを使うと、node_modulesが消えます。開発時のワークフローを、実際に踏んでから直します。

前回: Docker Composeの依存と環境変数 — depends_onを書いても落ちる

これは【深掘り】の記事です。本線の順路ではありません。 読まなくても先へ進めます。 本線の コンテナは軽い仮想マシンではない — Dockerの導入 の続きとして、そこでは「イメージを作って動かす」までしかやっていない部分を、毎日コードを書く側からやり直す回です。

この記事のコマンドは、断りがない限りすべてVMの中(Ubuntu Server)で打ちます。 前提: Dockerの導入を終えて、docker ps が sudo なしで通ること。 前提2: APIの正体はJSONを返すHTTP と node_modulesは消してよい を読んでいると、この記事の題材がそのまま読めます。 本線で作ったものには触りません。 練習用に ~/devlab を新しく作って、そこだけで完結させます。

Docker を覚えた直後、私は毎日こうしていました。

コードを1行直す。保存する。ターミナルに戻る。

docker compose build
docker compose up -d

40秒待つ。 ブラウザを再読み込みする。文字が1つ違う。また直す。また40秒待つ。

1日で何十回もやりました。「Docker を使うと開発が遅くなる」と本気で思っていました。

違いました。開発中にイメージを作り直すのは、そもそも間違いです。 イメージを作り直すのは「配る形にするとき」の作業で、書いている最中にやることではありません。書いている最中は、ホストのソースをコンテナの中に見せて、直したら即座に反映させるのが正しい形です。

ただし、その形にするとほぼ全員が同じ事故を踏みます。 node_modules が消えるやつです。この回は、そこを含めて全部踏みに行きます。

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

目次

この記事でわかること

  • 開発中に docker build を繰り返すのは、道具の使い方が間違っている。ビルドは「配るとき」の作業
  • ソースを bind mount すると、コンテナの中の node_modules がホスト側のもので覆い隠されて「消える」。これは Docker の不具合ではなく、マウントの定義どおりの動作
  • ホストで npm install したものは、コンテナの中で動くとは限らない。ネイティブモジュールはOSとlibcに合わせて作られている
  • ファイル変更が検知されないのは、共有フォルダ越しだとOSの通知イベントが飛んでこないから。監視方式を変えれば直る
  • --inspect は既定で 127.0.0.1 にしか口を開けない。コンテナの中の 127.0.0.1 は外から届かない
  • 開発用と本番用は同じ Dockerfile で書ける。マルチステージの「途中の段」を名前で選ぶ
  • 開発で当たり前にやっていることの大半は、本番でやると穴になる

この記事でやること

  1. ~/devlab に小さな Node.js のAPIを作り、直すたびにビルドし直す遅さを一度体験する
  2. ソースを bind mount して、--watch で自動再起動させる
  3. node_modules が消える事故を実際に起こして、匿名ボリュームで覆って直す
  4. 変更が検知されない場合に、ポーリング監視へ切り替える
  5. --inspect=0.0.0.0:9229 と VS Code の attach で、コンテナの中にブレークポイントを掛けて止める
  6. docker compose watch を使い、sync と rebuild の違いを確かめる
  7. 開発用と本番用を target で分けて、最後に片づける

先に知る言葉

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

言葉意味
ホットリロードソースを保存した瞬間に、動いているプログラムへ反映させること。ここでは「保存したら自動で再起動」の意味で使う
bind mountホストの特定のフォルダを、コンテナの中の場所に直接見せる方式。中身はホスト側が正
匿名ボリューム名前を付けずに作られる Docker 管理の保存領域。-v /app/node_modules のように行き先だけ書くと作られる
ネイティブモジュールJavaScript ではなくC/C++で書かれ、インストール時に機械語へコンパイルされる部品。bcrypt などが該当
libcOSが用意する基本の関数集。Ubuntu は glibc、Alpine は musl で別物
inotifyLinux が「このファイルが変わった」とプログラムに知らせる仕組み。共有フォルダ越しには飛ばないことがある
ポーリング通知を待たず、自分から定期的に見に行く方式。確実だが遅く、CPUを食う
Inspector プロトコルNode.js が持つデバッグ用の通信口。ポート 9229 で待ち受ける
attach(アタッチ)既に動いているプロセスに、あとからデバッガを繋ぐこと。プログラムを起動し直さない
マルチステージビルド1つの Dockerfile に複数の FROM を書き、段ごとに名前を付けて使い分ける書き方

① 練習用のAPIを作り、「毎回ビルドし直す」を一度だけ体験する

まず作業場所を作ります。本線で作ったものとは別のフォルダです。

bash
$ mkdir -p ~/devlab/src && cd ~/devlab

package.json を作ります。

bash
$ nano package.json
{
  "name": "devlab",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node src/server.js",
    "dev": "node --watch src/server.js"
  }
}

次にAPI本体です。

bash
$ nano src/server.js
import http from 'node:http';

const PORT = 3000;

function totalPrice(items) {
  let total = 0;
  for (const item of items) {
    total += item.price * item.count;
  }
  return total;
}

const server = http.createServer((req, res) => {
  console.log(`${req.method} ${req.url}`);

  if (req.url === '/health') {
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ status: 'ok' }));
    return;
  }

  if (req.url === '/total') {
    const items = [
      { name: 'coffee', price: 480, count: 2 },
      { name: 'bagel', price: 320, count: 1 }
    ];
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ total: totalPrice(items) }));
    return;
  }

  res.writeHead(404, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ error: 'not found' }));
});

server.listen(PORT, '0.0.0.0', () => {
  console.log(`listening on 0.0.0.0:${PORT}`);
});

server.listen の第2引数に 0.0.0.0 を書いています。 ここを省略したり 127.0.0.1 と書いたりすると、コンテナの外から繋がりません。 理由は localhostで繋がらないのは当然 でやったとおりです。

Dockerfile を、まず素朴に書きます。

bash
$ nano Dockerfile
FROM node:22-alpine
WORKDIR /app
COPY package.json ./
RUN npm install --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "src/server.js"]

ビルドして動かします。

bash
$ docker build -t devlab:v1 .
$ docker run -d --name devlab -p 3000:3000 devlab:v1
$ curl -s localhost:3000/total
{"total":1280}

ここまでは本線でやったとおりです。 問題はここからです。total の計算に消費税を足したくなったとします。src/server.js の totalPrice を1行直します。

bash
$ nano src/server.js
  return Math.round(total * 1.1);

そして反映させます。

bash
$ curl -s localhost:3000/total
{"total":1280}

変わりません。 当然です。コンテナの中で動いているのは、ビルドした瞬間にコピーされたファイルであって、いま編集したファイルではありません。反映させるには、

bash
$ docker rm -f devlab
$ docker build -t devlab:v1 .
$ docker run -d --name devlab -p 3000:3000 devlab:v1
$ curl -s localhost:3000/total
{"total":1408}

この3行を、1文字直すたびに打っていました。 1回あたり数十秒。1日100回直せば、それだけで1時間が消えます。

なぜ COPY . . の行でキャッシュが効かないのかは レイヤーキャッシュは行の順番で決まる でやりました。ソースをコピーした行より下は毎回やり直しになります。キャッシュを整えても、この待ち時間はゼロにはなりません。


② ソースを bind mount して、直したら即反映させる

発想を変えます。 ビルドのたびにソースを「焼き込む」のをやめ、ホストのフォルダをコンテナの中に見せるようにします。

bash
$ docker rm -f devlab
$ docker run -d --name devlab -p 3000:3000 -v ~/devlab/src:/app/src devlab:v1

-v ホストの場所:コンテナの中の場所 が bind mount です。中身の正はホスト側になります。詳しくは コンテナを消すとデータも消える を見てください。

ソースを直します。今度は税率を 1.08 に変えてみます。

bash
$ sed -i 's/1\.1/1.08/' ~/devlab/src/server.js
$ curl -s localhost:3000/total
{"total":1408}

まだ変わりません。 ここが2段構えになっているところです。

  • ファイルは確かに入れ替わっています。 それは確認できます
bash
$ docker exec devlab grep 1.08 /app/src/server.js
  return Math.round(total * 1.08);
  • しかし Node.js は、起動したときに読んだものをメモリに持ったままです。ファイルが変わっても勝手には読み直しません

つまり bind mount は「ファイルを届ける」ところまでしかやってくれないということです。読み直させる担当が別に要ります。

--watch で再起動させる

Node.js 18.11 以降には --watch が入っています。外部のツールを入れなくてもよくなりました。

bash
$ docker rm -f devlab
$ docker run -d --name devlab -p 3000:3000 \
    -v ~/devlab/src:/app/src \
    devlab:v1 node --watch src/server.js

最後の node --watch src/server.js は、イメージに書いてある CMD を上書きしています。 docker run の引数の順番については docker runの長い1行が読めない を見てください。

確かめます。

bash
$ curl -s localhost:3000/total
$ sed -i 's/1\.08/1.10/' ~/devlab/src/server.js
$ curl -s localhost:3000/total
{"total":1382}
{"total":1408}

ビルドせずに変わりました。 ログにも再起動が残っています。

bash
$ docker logs --tail 5 devlab
Restarting 'src/server.js'
listening on 0.0.0.0:3000

これが開発中の正しい形です。 docker build は、ライブラリを足したときにだけ打ちます。


③ node_modules が消える — 全員が踏む事故

ここまでは src だけをマウントしていたので何も起きませんでした。しかし、ふつうはこう書きたくなります。

「package.json を直したときも反映してほしいから、フォルダごとマウントしよう」

その前に、ライブラリを1つ入れておきます。

bash
$ cd ~/devlab
$ nano package.json
{
  "name": "devlab",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "dayjs": "1.11.13"
  },
  "scripts": {
    "start": "node src/server.js",
    "dev": "node --watch src/server.js"
  }
}

src/server.js の先頭に1行足して、使います。

import dayjs from 'dayjs';

そして /health の応答に時刻を混ぜます。

    res.end(JSON.stringify({ status: 'ok', now: dayjs().format('YYYY-MM-DD HH:mm:ss') }));

イメージを作り直します。ライブラリを足したときは、ここは必要です。

bash
$ docker build -t devlab:v1 .

さて、フォルダごとマウントします。

bash
$ docker rm -f devlab
$ docker run -d --name devlab -p 3000:3000 \
    -v ~/devlab:/app \
    devlab:v1 node --watch src/server.js
$ docker logs devlab
node:internal/modules/esm/resolve:283
  throw new ERR_MODULE_NOT_FOUND(
        ^
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'dayjs' imported from /app/src/server.js

イメージの中には確かに入れたのに、無いと言われます。

中を見ると、はっきりします。

bash
$ docker run --rm devlab:v1 ls /app
Dockerfile
node_modules
package.json
src
bash
$ docker run --rm -v ~/devlab:/app devlab:v1 ls /app
Dockerfile
package.json
src

node_modules が消えています。

なぜ消えるのか

消えていません。隠れています。

bind mount は「ホストのフォルダを、コンテナの中のその場所にかぶせる」動作です。/app にホストの ~/devlab をかぶせた瞬間、/app から見えるものは、ホストの ~/devlab の中身がすべてになります。イメージに入っていた /app/node_modules は、下敷きになって見えなくなります。

ホスト側には node_modules がありません(VMでは npm install していないので)。だから無いものが見えているわけです。

これは Docker の不具合ではありません。 「かぶせる」という定義そのままの動きです。知らないと絶対に分からないだけです。

直しかた — 匿名ボリュームで覆い返す

かぶせられたのなら、その1か所だけを、さらにかぶせ返します。

bash
$ docker rm -f devlab
$ docker run -d --name devlab -p 3000:3000 \
    -v ~/devlab:/app \
    -v /app/node_modules \
    devlab:v1 node --watch src/server.js
$ curl -s localhost:3000/health
{"status":"ok","now":"2026-09-23 06:11:42"}

動きました。

-v /app/node_modules は、コロンが無く、行き先だけを書いています。これは「この場所には、Docker が管理する入れ物を置け」という指定で、匿名ボリュームが作られます。

大事なのは順番ではなく深さです。マウントはパスの深いほうが勝ちます。

場所何が見えるか
/appホストの ~/devlab(bind mount)
/app/node_modules匿名ボリューム(より深いので、こちらが勝つ)

そして匿名ボリュームは、中身が空のときに限り、イメージの同じ場所にあったものが最初にコピーされます。 だからイメージのビルド時に npm install した結果がそこに現れます。

確かめます。

bash
$ docker exec devlab ls /app/node_modules | head -3
$ docker volume ls | tail -2
.package-lock.json
dayjs
DRIVER    VOLUME NAME
local     8f3c1a...(長い16進数)

匿名ボリュームは、コンテナを消しても残ります。 docker rm -f を繰り返していると静かに溜まります。消すときは docker rm -v を使うか、あとで docker volume prune します(この記事の後片づけでやります)。

Compose で書くなら、こうなります。

services:
  app:
    build: .
    volumes:
      - ./:/app
      - /app/node_modules

リストの2行目、コロンの左が無い行が匿名ボリュームです。この1行の意味を知らずにコピーしている人が多いところです。


④ ホストとコンテナでOSが違うと、ネイティブモジュールが壊れる

「じゃあ、ホスト側で npm install して、その node_modules をそのまま使えばいいのでは」

そう思うのが自然です。そして、そこが2つ目の罠です。

VM(Ubuntu)側で入れてみます。

bash
$ cd ~/devlab
$ npm install
$ ls node_modules | head -3
.package-lock.json
dayjs

これで匿名ボリュームを外しても動きます。

bash
$ docker rm -f devlab
$ docker run -d --name devlab -p 3000:3000 -v ~/devlab:/app \
    devlab:v1 node --watch src/server.js
$ curl -s localhost:3000/health
{"status":"ok","now":"2026-09-23 06:18:05"}

動いてしまいます。 dayjs は純粋な JavaScript だけでできているからです。ファイルをどこにコピーしても同じように動きます。

問題は、C/C++で書かれたライブラリを入れたときに起きます。パスワードのハッシュに使う bcrypt などが該当します。これらは npm install したその瞬間に、その環境向けに機械語へコンパイルされます。

つまり、

どこで npm install したかできあがる部品
VM(Ubuntu / glibc)glibc 向けのバイナリ
コンテナ(node:22-alpine / musl)musl 向けのバイナリ
Windows 本体Windows 向けのバイナリ(拡張子は同じ .node だが、中身は Windows の DLL 形式)

この3つは互換ではありません。 ホストで作ったものをコンテナに見せると、こういうエラーになります。

Error: Error loading shared library ld-linux-x86-64.so.2: No such file or directory

あるいは、

Error: /app/node_modules/bcrypt/lib/binding/napi-v3/bcrypt_lib.node:
  invalid ELF header

invalid ELF header は「バイナリの形式が違う」という意味です。 Windows で npm install したものを Linux コンテナに持ち込むと、これがよく出ます。ライブラリを疑う前に、どこで install したかを疑ってください。

結論はこうです。

  • node_modules はホストとコンテナで共有しない。 匿名ボリュームで分ける(③でやったこと)
  • ホスト側の node_modules は、エディタの補完のためだけに置く。動かすのはコンテナの中のもの
  • どちらか片方だけを正にする。 混ぜたときだけ壊れる

いま VM 側に作ってしまった node_modules は、混乱の元なので消しておきます。

bash
$ rm -rf ~/devlab/node_modules

消して構いません。 node_modules は package.json から何度でも作り直せます(node_modulesは消してよい)。

そして .dockerignore を置いて、うっかりホストの node_modules がイメージに入らないようにします。

bash
$ nano ~/devlab/.dockerignore
node_modules
npm-debug.log
.git
.env

これはイメージを小さくするためだけの話ではありません。 ホスト側の(壊れているかもしれない)node_modules が COPY . . で持ち込まれるのを防ぐためです。イメージの大きさについては 1.2GBのイメージが50MBになる を見てください。


⑤ ファイルを直しても、再起動してくれない

ここまでは順調に動いたはずです。ところが、環境によっては②の時点で再起動しません。

bash
$ docker logs --tail 3 devlab
listening on 0.0.0.0:3000

ファイルを直しても、Restarting の行が出ません。 docker exec で中を見るとファイルは確かに変わっているのに、です。

何が起きているか

--watch も nodemon も、内部では inotify(Linux の「ファイルが変わった」通知)を使っています。この通知は、書き換えたのと同じOSのカーネルの中でしか飛びません。

だから、こういう経路だと通知が届きません。

経路変更が検知されるか
VM の中の ~/devlab を、VM 内のコンテナへ bind mount検知される(同じカーネル)
Windows のフォルダを VMware の共有フォルダ越しにマウント飛ばないことが多い
ネットワークドライブ・NFS・SMB 越し飛ばない
Docker Desktop(Windows / macOS)でホストのフォルダをマウント仕組み次第。落ちることがある

ファイルは届いているのに、届いたことを知らせる人がいない状態です。

直しかた — 自分から見に行く(ポーリング)

通知が来ないなら、定期的に自分で見に行けばよいということになります。それがポーリングです。

node --watch にはポーリングへ切り替える設定がありません。ここは nodemon に替えます。

bash
$ cd ~/devlab
$ nano package.json
{
  "name": "devlab",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "dayjs": "1.11.13"
  },
  "devDependencies": {
    "nodemon": "3.1.7"
  },
  "scripts": {
    "start": "node src/server.js",
    "dev": "nodemon src/server.js"
  }
}

devDependencies に入れています。 本番のイメージには入れたくないからです(⑧でその分け方をやります)。

Dockerfile の npm install --omit=dev は開発ツールを落としてしまうので、開発用には向きません。ここも⑧で分けますが、いまは確かめるためにこう打ちます。

bash
$ docker build -t devlab:v1 .
$ docker rm -f devlab
$ docker run -d --name devlab -p 3000:3000 \
    -v ~/devlab:/app \
    -v /app/node_modules \
    -e CHOKIDAR_USEPOLLING=true \
    -e CHOKIDAR_INTERVAL=1000 \
    devlab:v1 sh -c "npm install && npx nodemon src/server.js"

CHOKIDAR_USEPOLLING=true は、nodemon が内部で使っている chokidar というファイル監視ライブラリへの指示です。「通知を待たず、1秒ごとに全部見に行け」という意味になります。

bash
$ sed -i 's/1\.10/1.15/' ~/devlab/src/server.js
$ docker logs --tail 4 devlab
[nodemon] restarting due to changes...
[nodemon] starting `node src/server.js`
listening on 0.0.0.0:3000

今度は反応しました。

ポーリングは最後の手段です。 ファイル数が多いと常時CPUを食い続けます(node_modules を監視対象から外していないと顕著です)。まず通知方式で試し、動かないときだけ切り替えてください。

そして、そもそも Windows 側のフォルダをVMへ共有して開発しないのが一番きれいな解です。ソースはVMの中に置き、VS Code の Remote – SSH でVMの中を直接編集すると、この問題は最初から起きません。

[スクリーンショット: 01_nodemon再起動ログ.png] docker logs -f devlab を出したまま別の端末でソースを保存し、[nodemon] restarting due to changes... が流れた瞬間を撮ってください。


⑥ コンテナの中の Node.js にデバッガを繋ぐ

console.log を挟んで、docker logs で見る。しばらくはそれで足ります。 ですが、変数が10個あるときや、ループの3周目だけおかしいときには限界が来ます。

動いているプロセスを止めて、その場の変数を全部見たい。 それがデバッガです。

--inspect を開く。0.0.0.0 にしないと届かない

Node.js は --inspect を付けると、ポート 9229 でデバッガの接続を待ちます。

まず、間違ったほうを先にやります。

bash
$ docker rm -f devlab
$ docker run -d --name devlab -p 3000:3000 -p 9229:9229 \
    -v ~/devlab:/app -v /app/node_modules \
    devlab:v1 sh -c "npm install && node --inspect src/server.js"
$ docker logs --tail 3 devlab
Debugger listening on ws://127.0.0.1:9229/2f0c...
For help, see: https://nodejs.org/en/docs/inspector

VM から繋ぎに行きます。

bash
$ curl -s localhost:9229/json/list
curl: (56) Recv failure: Connection reset by peer

ポートは -p 9229:9229 で公開したのに、繋がりません。

理由は1行目に書いてあります。ws://127.0.0.1:9229。

127.0.0.1 は「自分自身」という意味です。そしてコンテナの中の「自分自身」は、コンテナの中だけを指します。ホストから来た通信は、コンテナの外側の口(0.0.0.0 側)に届くので、127.0.0.1 でしか待っていないプロセスには渡りません。

これは本線の nginx でも同じ形で出ました。 -p は「コンテナの外の口とコンテナの中の口を繋ぐ」だけで、中のプロセスがどの住所で待つかまでは面倒を見ません。 詳しくは localhostで繋がらないのは当然。

待ち受ける住所を明示します。

bash
$ docker rm -f devlab
$ docker run -d --name devlab -p 3000:3000 -p 9229:9229 \
    -v ~/devlab:/app -v /app/node_modules \
    devlab:v1 sh -c "npm install && node --inspect=0.0.0.0:9229 src/server.js"
$ docker logs --tail 3 devlab
Debugger listening on ws://0.0.0.0:9229/9a41...
bash
$ curl -s localhost:9229/json/list | head -5
[ {
  "description": "node.js instance",
  "devtoolsFrontendUrl": "devtools://devtools/bundled/js_app.html?ws=localhost:9229/9a41...",
  "id": "9a41...",

繋がりました。

書き方誰から繋げるか
--inspectコンテナの中からだけ(既定は 127.0.0.1:9229)
--inspect=0.0.0.0:9229コンテナの外から繋げる
--inspect-brk=0.0.0.0:9229同上。ただし1行目を実行する前で止まって待つ。起動直後の処理を追いたいとき

VS Code から attach する

ここだけ Windows 側の VS Code の作業です。 Remote – SSH でVMに繋いだ状態で ~/devlab を開いてください。

設定ファイルを1つ置きます。全文です。

bash
$ mkdir -p ~/devlab/.vscode
$ nano ~/devlab/.vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Docker: Node にアタッチ",
      "type": "node",
      "request": "attach",
      "port": 9229,
      "address": "localhost",
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "/app",
      "skipFiles": ["<node_internals>/**"],
      "restart": true
    }
  ]
}

この設定で一番大事なのは localRoot と remoteRoot の2行です。

  • VS Code が見ているファイルは ~/devlab/src/server.js
  • コンテナの中の Node.js が見ているのは /app/src/server.js

同じファイルなのに、住所が違います。 この対応を教えないと、ブレークポイントは灰色の丸のままになって止まりません。 「設定したのに止まらない」の原因は、ほぼここです。

  • "request": "attach" は「すでに動いているものに繋ぐ」という指定です。launch にすると VS Code が Node.js を新しく起動しようとして、コンテナとは無関係のプロセスに繋ぎます
  • "restart": true は、nodemon が再起動したときに繋ぎ直す指定です。これが無いと、保存するたびにデバッガが外れます

ブレークポイントで止める

  1. VS Code で src/server.js を開く
  2. totalPrice の中の total += item.price * item.count; の行番号の左側をクリックして、赤い丸を付ける
  3. 左のデバッグアイコン(虫のマーク)→ 上の一覧から「Docker: Node にアタッチ」→ 緑の再生ボタン
  4. VM の端末で叩く
bash
$ curl -s localhost:3000/total

curl が返ってきません。止まっているからです。 VS Code の左側「変数」に、いまの値が並んでいます。

Local
  item: {name: 'coffee', price: 480, count: 2}
  total: 0

F10(ステップオーバー)で1行ずつ進めると、total が 960 → 1280 と変わっていくのが見えます。F5 で最後まで流すと、curl が返ってきます。

console.log を10個仕込むより速いことが、ここで分かります。

[スクリーンショット: 02_VSCodeブレークポイント.png] VS Code でブレークポイントに止まり、左の「変数」パネルに total と item が出ている画面を撮ってください。

[スクリーンショット: 03_inspect接続確認.png] curl -s localhost:9229/json/list が JSON を返している画面を撮ってください。

-p 9229:9229 は、そのポートを公開しているという意味です。 Inspector プロトコルには認証がありません。 繋げた人はコンテナの中で好きなコードを実行できます。 VM の中で閉じているうちは構いませんが、外に出るサーバーで開けてはいけません。 ⑩でまとめます。


⑦ docker compose watch — 新しいやり方

ここまでは docker run で長い1行を組み立ててきました。毎回これを打つのは現実的ではありません。 Compose にします。

bash
$ cd ~/devlab
$ nano compose.yaml
services:
  app:
    build:
      context: .
    ports:
      - "3000:3000"
      - "127.0.0.1:9229:9229"
    command: ["npx", "nodemon", "--inspect=0.0.0.0:9229", "src/server.js"]
    volumes:
      - ./:/app
      - /app/node_modules
    environment:
      NODE_ENV: development

9229 のほうだけ 127.0.0.1: を頭に付けています。 こう書くとVM の中からしか繋げなくなります。 VS Code は Remote – SSH でVMの中にいるので、これで届きます。デバッグ用の口は、必要な範囲より広く開けないのが基本です。

さらに、Compose には watch という仕組みがあります(Compose v2.22 以降)。bind mount とは考え方が違います。

    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
        - action: rebuild
          path: ./package.json

compose.yaml の app: の下に、上の7行を足してください。試す間は、volumes: の - ./:/app の行を消しておきます(理由は下で説明します)。そして、

bash
$ docker compose up --build --watch

別の端末でソースを直します。

bash
$ sed -i 's/1\.15/1.20/' ~/devlab/src/server.js

up --watch を出している側に、こう出ます。

Syncing service "app" after changes were detected
[nodemon] restarting due to changes...

次に package.json を直してみます(バージョンを上げるだけで構いません)。

bash
$ sed -i 's/"version": "1.0.0"/"version": "1.0.1"/' ~/devlab/package.json
Rebuilding service "app" after changes were detected

動作が変わりました。 ここが sync と rebuild の違いです。

action何をするか何に使うか
sync変わったファイルをコンテナの中へコピーするだけ。コンテナは動いたままソースコード。速い
rebuildイメージを作り直して、コンテナを入れ替えるpackage.json・Dockerfile。依存が変わるとき
sync+restartコピーしたうえでコンテナを再起動設定ファイルなど、読み直しが要るもの

sync と bind mount の違いも押さえておきます。

bind mount(volumes:)watch の sync
ファイルの居場所ホスト側が正。コンテナは覗いているだけコンテナの中にコピーされる。中身は2つある
通知が飛ばない環境検知されない(⑤の問題)Compose 自身が見張るので、比較的強い
遅い共有フォルダ越し読み込みが遅いコンテナ内のディスクなので速い
除外指定できないignore: で node_modules などを外せる

sync を使うなら、volumes: の bind mount は要りません。 両方書くと「ホストが正なのかコピーが正なのか」が分からなくなります。どちらか片方にしてください。

いったん止めます。

Ctrl + C

⑧ 開発用と本番用の Dockerfile を分ける

ここまでで、開発中のイメージには本番に要らないものが入り込んでいます。

  • nodemon(開発ツール)
  • --inspect で開くデバッグの口
  • root ユーザーで動いていること

かといって、Dockerfile を2つに分けるのは失敗します。 片方だけ直して、もう片方が古くなるからです。同じ Dockerfile の中で、段を分けます。

bash
$ nano ~/devlab/Dockerfile
# ---- 共通の土台 ----
FROM node:22-alpine AS base
WORKDIR /app
COPY package.json ./

# ---- 開発用 ----
FROM base AS dev
ENV NODE_ENV=development
RUN npm install
COPY . .
EXPOSE 3000 9229
CMD ["npx", "nodemon", "--inspect=0.0.0.0:9229", "src/server.js"]

# ---- 本番用 ----
FROM base AS prod
ENV NODE_ENV=production
RUN npm install --omit=dev && npm cache clean --force
COPY . .
USER node
EXPOSE 3000
CMD ["node", "src/server.js"]

FROM ... AS 名前 で段に名前を付けています。 そして FROM base AS dev のように、前の段を土台にして続きを書けます。

段入るもの動かす利用者デバッグの口
dev開発ツールも入る(npm install)root開ける
prod本番に要るものだけ(--omit=dev)node(一般利用者)開けない

作り分けます。

bash
$ cd ~/devlab
$ docker build --target dev -t devlab:dev .
$ docker build --target prod -t devlab:prod .
$ docker images devlab
REPOSITORY   TAG    IMAGE ID       SIZE
devlab       prod   3c1f9a2b7e04   142MB
devlab       dev    a70e5d813f6c   167MB

--target を付けないと、最後の段(ここでは prod)が使われます。 開発用を先に、本番用を後ろに書くと、うっかりビルドしたときに安全なほうができます。

Compose 側からは target: で選びます。

bash
$ nano ~/devlab/compose.yaml
services:
  app:
    build:
      context: .
      target: dev
    ports:
      - "3000:3000"
      - "127.0.0.1:9229:9229"
    volumes:
      - ./:/app
      - /app/node_modules
    environment:
      NODE_ENV: development
      CHOKIDAR_USEPOLLING: "false"
bash
$ docker compose up -d --build
$ curl -s localhost:3000/health
{"status":"ok","now":"2026-09-23 07:02:33"}

本番用の Compose ファイルでは target: prod にして、volumes: と 9229 の行を消します。 ファイルの重ね方(compose.override.yaml)は depends_onを書いても落ちる でやったとおりです。


⑨ ログは標準出力に出す

デバッガを繋ぐほどではないとき、見るのはログです。

bash
$ docker compose logs -f app

-f は「新しい行が出たら流し続ける」という意味です。別の端末で curl を打つと、その場で行が増えます。

app-1  | GET /total
app-1  | GET /health

止めるのは Ctrl + C です。これはログの表示を止めるだけで、コンテナは動き続けます。

よく使う形はこれだけです。

bash
$ docker compose logs --tail 50 app
$ docker compose logs -f --since 5m app

ログをファイルに書かない

ここが、VM に直接アプリを置いていたときとの一番大きな違いです。

コンテナの中のログファイルには、ほぼ意味がありません。

  • コンテナを作り直したら消えます(コンテナを消すとデータも消える)
  • docker logs にも docker compose logs にも出てきません
  • コンテナが3台に増えたら、3か所を別々に見に行くことになります

だから、コンテナの中のプログラムは、ログを標準出力(と標準エラー出力)に書きます。 console.log をそのまま使う、ということです。書き先を決めるのは、プログラムではなく外側の仕事になります。

プログラム → 標準出力 → Docker が受け取る → docker logs / 集約基盤へ

集めかたそのものは ログが3箇所に散っている と Prometheusは取りに行く でやりました。その入口は「アプリがファイルに書かないこと」です。


⑩ 開発でやってよくて、本番でやってはいけないこと

この記事でやったことは、ほとんどが本番では穴になります。 ここを混ぜないことが、この回の本当の要点です。

やっていること開発本番本番でだめな理由
ソースを bind mount する◯×イメージが「動くものの全部」でなくなる。別のサーバーに持っていくと動かない。ホスト側を書き換えれば中身をすり替えられる
root で動かす△×コンテナから抜け出せる欠陥が見つかったとき、被害が広がる。USER node を書く
--inspect の口を開ける◯絶対に×認証が無い。繋げた人は任意のコードを実行できる
npm install(開発ツール込み)◯×使わないものが増えるほど、直すべき欠陥も増える。--omit=dev
nodemon で動かす◯×監視の分だけ無駄。落ちたときの再起動は Docker の restart: の仕事
CHOKIDAR_USEPOLLING△×CPUを食い続ける。開発でも、必要なときだけ
NODE_ENV を未設定のまま△×ライブラリによってはエラーの詳細を外に返す。production を明示する
latest タグ△×どれが動いているか分からなくなる。バージョンを固定する
ポートを 0.0.0.0 で公開◯(VM内)△必要なポートだけ。デバッグ用は 127.0.0.1: を付けて閉じる

「開発で動いたから本番も同じでいい」が一番危ない、という一覧です。


つまずいたところ

遠回りしたところを、消さずに残します。

1. node_modules が消えたのを、Docker の不具合だと思った

docker build からやり直しました。キャッシュも消しました。docker system prune -a まで打ちました。当然ですが、何も変わりません。

原因が分かったのは、マウントする前と後で ls /app を並べて見たときです。

bash
$ docker run --rm devlab:v1 ls /app
$ docker run --rm -v ~/devlab:/app devlab:v1 ls /app

「マウントする前は在る」と分かった瞬間に、犯人はマウントに決まりました。 原因が分からないときは、疑っているものを外した状態と、付けた状態を並べるのが一番速いです。

2. ホストで npm install して解決したつもりになった

④でやったとおり、dayjs だけなら動いてしまいます。 そこで「解決した」と思い込みました。

数週間後、bcrypt を入れた日に invalid ELF header で止まり、そのときには原因の心当たりが多すぎて丸1日かかりました。たまたま動いたものは、いつか必ず落ちます。

3. ブレークポイントが灰色のまま止まらなかった

launch.json の port も address も合っていて、curl localhost:9229/json/list も返っていました。それでも止まりません。

原因は remoteRoot を書いていなかったことでした。VS Code は /home/user/devlab/src/server.js の何行目に止めろと言い、Node.js は /app/src/server.js しか知りません。話が噛み合っていなかっただけです。

「繋がっているのに止まらない」ならパスの対応を疑ってください。

4. --inspect を 0.0.0.0 にせず、ポートの公開を疑った

-p 9229:9229 を --network host に変えたり、ファイアウォールを止めたりしました。全部見当違いでした。

ログの1行目に ws://127.0.0.1:9229 と書いてあったのに、読んでいませんでした。エラーを読む前に設定を変え始めると、必ず遠回りします(エラーは下から読む)。

5. ポーリングを常時ONにして、VMが重くなった

⑤で直ったのが嬉しくて、すべての開発コンテナに CHOKIDAR_USEPOLLING=true を付けました。

top を見ると、何もしていないのに CPU が常に 30% ほど埋まっています。監視対象に node_modules の数万ファイルが入っていたためです。CHOKIDAR_USEPOLLING は、通知方式で動かないと確認できた場所にだけ付けてください。


後片づけ

この記事で作ったものだけを消します。

bash
$ cd ~/devlab
$ docker compose down
$ docker rm -f devlab

匿名ボリュームが溜まっているはずなので、数えてから消します。

bash
$ docker volume ls -qf dangling=true | wc -l
$ docker volume prune -f
6

docker volume prune は、既定では「どのコンテナからも使われていない匿名ボリューム」を消します(Docker 23 以降。名前付きまで消すのは --all を付けたとき)。--all を付けると、本線で作ったデータベースの名前付きボリュームも、使っていたコンテナを消したあとなら巻き込みます。 消す前に必ず docker volume ls を見てください。名前付きボリュームを残したいなら、prune ではなく名前を指定して消します。

イメージとフォルダを消します。

bash
$ docker rmi devlab:v1 devlab:dev devlab:prod
$ cd ~ && rm -rf ~/devlab
$ docker system df

本線で作ったものは消していません。 この記事は ~/devlab の中だけで完結しています。


まとめ — 理解できたこと

  • 開発中に docker build を繰り返すのは間違い。 ビルドは「配る形にするとき」の作業
  • bind mount は「ファイルを届ける」までしかやらない。 読み直させる担当(--watch / nodemon)が別に要る
  • node_modules は消えていない。ホスト側のフォルダをかぶせて隠しているだけ
  • マウントはパスの深いほうが勝つ。 だから -v /app/node_modules(コロン無し=匿名ボリューム)で覆い返せる
  • 匿名ボリュームは、空のときに限りイメージの同じ場所の中身が最初にコピーされる。だから npm install の結果が現れる
  • 匿名ボリュームはコンテナを消しても残る。 静かに溜まるので docker rm -v か docker volume prune
  • ネイティブモジュールは install した環境向けにコンパイルされる。 Ubuntu(glibc) と Alpine(musl) と Windows は互換ではない
  • invalid ELF header は「バイナリの形式が違う」。 ライブラリより先に、どこで install したかを疑う
  • node_modules はホストとコンテナで共有しない。 ホスト側のものは補完用、動かすのは中のもの
  • 変更が検知されないのは、inotify が共有フォルダ越しに飛ばないから。 ファイルは届いている
  • CHOKIDAR_USEPOLLING=true で自分から見に行く。 CPUを食うので最後の手段。本筋はソースをVMの中に置くこと
  • --inspect の既定は 127.0.0.1。 コンテナの中の「自分自身」には外から届かない。--inspect=0.0.0.0:9229
  • VS Code は request: attach で繋ぐ。 localRoot と remoteRoot を書かないとブレークポイントは止まらない
  • restart: true が無いと、nodemon の再起動でデバッガが外れる
  • compose watch の sync はコピー、rebuild はイメージごと作り直し。 ソースは sync、package.json は rebuild
  • sync と bind mount は併用しない。 どちらが正か分からなくなる
  • 開発用と本番用は Dockerfile を分けない。 マルチステージの段に名前を付けて --target / target: で選ぶ
  • --target を省くと最後の段が使われる。 本番用を最後に書いておくと、うっかりが安全側に倒れる
  • ログはファイルに書かず標準出力へ。 書き先を決めるのは外側の仕事
  • bind mount・root 実行・--inspect の公開は、開発だけのもの。 本番に持ち込まない

参考リンク


次に読む

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

記事
← 前の記事Docker Composeの依存と環境変数 — depends_onを書いても落ちる
→ 次の記事DockerでCIのテストを回す — 手元では通るのにCIで落ちる

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

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

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

DevOps›Docker — Developer Experience
  • bind mount とホットリロード
  • コンテナの中をデバッグする

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

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

コメント

コメントする

目次