docker compose watchで開発環境のホットリロードを実現する方法｜sync・rebuild・sync+restartの使い分けと実践設計

この記事のポイント

・docker compose watch は v2.22+ で正式化された自動反映機能
・compose.yml の develop.watch ブロックに path・action・target を設定する
・sync（即時同期）・rebuild（再ビルド）・sync+restart（同期後再起動）を用途で使い分ける
・docker compose up --watch の一発起動でも同じ効果が得られる

# 従来の開発フロー（手動再起動が必要）
$ vim src/app.js          # コードを編集
$ docker compose restart web  # コンテナを再起動
$ curl localhost:3000     # 動作確認

$ docker compose version
Docker Compose version v2.27.1

services:
  web:
    build: .
    ports:
      - "3000:3000"
    develop:
      watch:
        - action: sync          # アクション種別
          path: ./src           # 監視するホスト側パス
          target: /app/src      # コンテナ内の同期先パス
          ignore:
            - node_modules/     # 監視除外パス
        - action: rebuild       # 別のルール
          path: package.json

develop:
  watch:
    - action: sync
      path: ./src
      target: /app/src
      ignore:
        - node_modules/
        - "*.test.js"

develop:
  watch:
    - action: rebuild
      path: package.json
    - action: rebuild
      path: Dockerfile

develop:
  watch:
    - action: sync+restart
      path: ./nginx.conf
      target: /etc/nginx/nginx.conf

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .

CMD ["npx", "nodemon", "src/index.js"]

services:
  web:
    build: .
    ports:
      - "3000:3000"
    develop:
      watch:
        # src/ 以下を変更したら即時同期（nodemon が検知して自動再起動）
        - action: sync
          path: ./src
          target: /app/src
          ignore:
            - node_modules/

        # package.json が変わったら再ビルド（npm install を再実行）
        - action: rebuild
          path: package.json

# watch を有効にして起動する（推奨）
$ docker compose up --watch

# または別ターミナルで watch だけ起動する
$ docker compose up -d
$ docker compose watch

$ docker compose up --watch
[+] Building 12.3s (10/10) FINISHED
[+] Running 1/1
 ✔ Container myapp-web-1  Started
Watch enabled
 - watching src, action sync to /app/src (ignoring node_modules/)
 - watching package.json, action rebuild

# src/index.js を保存したとき
Watch: Syncing service "web" after changes were detected:
  - "src/index.js"
[web] [nodemon] restarting due to changes...
[web] [nodemon] starting `node src/index.js`
[web] Server listening on port 3000

# package.json を保存したとき
Watch: Rebuilding service "web" due to changed files:
  - "package.json"
[+] Building 8.4s (10/10) FINISHED
[+] Running 1/1
 ✔ Container myapp-web-1  Started

$ docker compose version
Docker Compose version v2.18.1    ← v2.22 未満は非対応

# アップデート方法（Linux の場合）
$ curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64   -o /usr/local/lib/docker/cli-plugins/docker-compose
$ chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
$ docker compose version
Docker Compose version v2.27.1   ← アップデート成功

# NG例：develop が services の外に出てしまっている
services:
  web:
    build: .
develop:       # ← services: web: の下に入っていない
  watch: ...

# OK例：develop は services > サービス名 の直下
services:
  web:
    build: .
    develop:   # ← services: web: の下に正しく入っている
      watch: ...

# NG例：絶対パスは使えない
- action: sync
  path: /home/user/myapp/src    # 動作しない

# OK例：compose.yml からの相対パス
- action: sync
  path: ./src                    # compose.yml と同じ階層の src/

# 整理前（bind mount と watch の混在）
services:
  web:
    volumes:
      - ./src:/app/src    # bind mount
    develop:
      watch:
        - action: sync    # watch も設定（競合しやすい）
          path: ./src
          target: /app/src

# 整理後（watch に統一）
services:
  web:
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
          ignore:
            - node_modules/