第58章：Composeデバッグ（複数サービスでの見方）🧩🔍

複数サービス（API＋DB）になると、**「どこが悪いのか分からない😵」**が一気に増えます。でも大丈夫！この章は、原因を“サービス単位”で切り分ける型を身につけます💪✨

この章でできるようになること（ゴール）🎯✨

どのサービスが原因かを、手順通りに特定できる🔎
API / DB / 設定 / 起動順のどれ問題か、当たりをつけられる🎯
docker compose ps / logs / exec / config / events を使い分けできる🧰
「直ったっぽいけど不安😥」を卒業して、再発防止までできる🛡️

まず“地図”を頭に入れる🗺️🐳

Composeはざっくりこの3階建て🏢

プロジェクト：このフォルダのCompose一式（名前はだいたいフォルダ名が元）📁 -p でプロジェクト名を変えられるよ🧩 (Docker ドキュメント)
サービス：api / db みたいな「役割」単位👥（YAMLで定義するやつ）
コンテナ：サービスが実際に動いてる“実体”📦

そしてComposeファイルは、今は Compose Specification が推奨の最新形式だよ📌 (Docker Documentation)

まずは5分で状況把握セット⏱️👀✨（ここが最重要）

① docker compose ps：今“生きてる？”を一発確認🧟‍♂️✅

どのコンテナが running / exited / (healthy) なのか
ポート公開が意図通りかが見える！ (Docker Documentation)

docker compose ps

② docker compose logs：原因はだいたいログにいる🪵🔥

logs は「複数サービスのログをまとめて」見られるのが強い！ (Ask Ubuntu)

まずはサービスを絞るのがコツ👇

docker compose logs --tail=200 api
docker compose logs --tail=200 db

追いかけたい時（追尾）👇

docker compose logs -f --tail=200 api

③ docker compose events：再起動ループとか“挙動”を掴む🔁👂

「いつ落ちた？」「いつ再作成された？」が分かる！ (Matsuand)

docker compose events

④ docker compose config：YAMLの“最終形”を出して答え合わせ🧩✅

.env や環境変数の展開、複数ファイル合成後の姿を確認できる✨ (Matsuand)

docker compose config

⑤ docker compose exec：現場（コンテナ内）に入り込む🔦🕵️

「本当にその環境変数ある？」「名前解決できる？」を中で確かめる！

docker compose exec api sh

（bash が無いイメージも多いので、まず sh が安全🙂）

切り分けの“型”📐✨（これで迷子にならない）

困ったらこの順番でOK👇

psで“落ちてるサービス”を特定（exited がいない？ healthy になってる？）
logsで“最初のエラー”を拾う（最後じゃなくて「最初の例外」👀）
エラーの種類で分岐
- 接続系（ECONNREFUSED / timeout）→ ネットワーク or 起動順 or 接続先
- 認証系（password authentication failed）→ ユーザー/パス/DB名
- 設定系（env undefined / parse error）→ compose config
execで“中の事実”を確認（環境変数・DNS・ポート）
直したら upで反映（restart だけで済ませない！）

ちなみに docker compose restart は「YAMLやenv変更が反映されないことがある」ので、設定を直した後は up で作り直す方が安全だよ🙂 (Docker Documentation)

ハンズオン：DB接続不良を追う（API/DB/設定の切り分け）🧪🔥

題材：Todo API（api）＋ PostgreSQL（db）で、APIがDBに繋がらない😵 を解決する！

0) わざと失敗を仕込む😈（学習は再現が9割）

例：api の接続先を localhost にしてしまう（ありがちNo.1🪤）

（例のcompose.yaml断片：※雰囲気でOK、あなたの構成に合わせてね🙂）

services:
  api:
    environment:
      DATABASE_URL: postgresql://postgres:postgres@localhost:5432/todo
  db:
    image: postgres:16

1) 起動して、まず ps 👀

最近の docker compose up には --wait（running/healthy まで待つ） がある！便利！ (Docker Documentation)

docker compose up -d --wait
docker compose ps

api が exited なら：まず api のログ
db が exited なら：まず db のログ
両方 running でも、中身は死んでることがある → logs へ

2) logs：API側の“最初の例外”を拾う🪵🔍

docker compose logs --tail=200 api

たぶんこういう匂いがするはず👇

ECONNREFUSED 127.0.0.1:5432
connect ECONNREFUSED
timeout

ここで “127.0.0.1（=localhost）” が出たら、ほぼ勝ち🎉 **コンテナ内の localhost は「そのコンテナ自身」**だから、DBじゃないよね😅

3) logs：DB側も見て「DBは元気？」を確認🩺

docker compose logs --tail=200 db

DBが起動途中なら「ready to accept connections」的なログの前後を見る👀
認証系エラーならユーザー/パス/DB名の線が濃い🔥

4) exec：api コンテナの中で“事実確認”🔦

docker compose exec api sh

中でこれを見る👇

(a) 環境変数がどうなってる？

printenv | sort

(b) 接続先ホスト名が “db” になってる？

Compose では基本、サービス名（db）で繋ぐのが王道🧠✨
localhost は罠🪤

5) 解決：接続先を db に直す✅✨

services:
  api:
    environment:
      DATABASE_URL: postgresql://postgres:postgres@db:5432/todo

直したら restart ではなく up（作り直し）がおすすめ！

docker compose up -d
docker compose ps
docker compose logs --tail=100 api

“起動順/DB準備できてない問題”もついでに潰す🧯✨

DBは コンテナが起動しても、すぐ使えるとは限らない。そこで healthcheck + depends_on を使うと安定しやすいよ🙂 (Docker Documentation)

例：db に healthcheck を入れて、api は healthy 待ちにする🫶

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: todo
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d todo"]
      interval: 10s
      timeout: 5s
      retries: 5

  api:
    depends_on:
      db:
        condition: service_healthy

これで docker compose up -d --wait が効きやすくなる👍（healthy を待てる） (Docker Documentation)

さらに強い技：デバッグ専用サービスを“必要な時だけ”起動する🧰✨

「apiの中に curl とか入ってなくて調べられない😇」問題、あるある。

Compose の profiles を使うと、**デバッグ用サービスを“普段は起動しない”**にできる！ (Docker Documentation)

services:
  debug:
    image: nicolaka/netshoot
    profiles: ["debug"]
    command: ["sleep", "infinity"]

必要な時だけ起動👇

docker compose --profile debug up -d
docker compose exec debug sh

debug の中で（例）👇

curl http://api:3000/health
nc -vz db 5432
dig db

みたいに“ネットワークの事実確認”が一気にできる😆🌐

Composeデバッグでよくある罠ランキング🪤🏆

1位：直したのに反映されてない（restart しただけ）😵

設定を変えたら up で反映が安全
restart は「設定変更が反映されないケースがある」 (Docker Documentation)

2位：孤児コンテナ（昔のサービスが残ってる）👻

掃除したいなら down の --remove-orphans が効く🧹 (Docker Documentation)

docker compose down --remove-orphans

3位：ボリューム消して、データも消えた😭

down の -v は named volume も消すので注意⚠️ (Docker Documentation)

docker compose down -v

AI活用（そのままコピペでOK）🤖✨

ログ解析プロンプト🪵

「このログ、原因は (設定/起動順/ネットワーク/認証/アプリバグ) のどれっぽい？上から順に可能性と確認コマンドを出して」

Compose診断プロンプト🧩

「docker compose ps の結果と compose config の一部を貼るので、怪しい差分を指摘して。直すならどこ？」

再発防止プロンプト🛡️

「今回の原因を“チェックリスト”にして。次から5分で潰せる手順にして」

ミニ課題🎒✨（5〜15分）

api の DATABASE_URL をわざと壊す → logs で原因特定 → 直す✅
db のパスワードをわざと変える → 認証エラーを見分ける🔐
profiles で debug サービスを追加 → db:5432 に到達確認する🌐

まとめ🏁🎉

Composeデバッグは 「サービス単位で切る」→「事実確認」→「反映」 の繰り返し🔁
最初は ps → logs → exec → config → events の順でOK🧭
起動順やready問題は healthcheck + depends_on + up --wait で安定しやすい🛡️ (Docker Documentation)
“調査用サービス”を profiles で持つと、詰まりが激減する😆🧰 (Docker Documentation)

次の章（第59章）は、この章で作った手順をさらに圧縮して「詰まり総復習チェックリスト化」だよ📋✨

この章でできるようになること（ゴール）🎯✨​

まず“地図”を頭に入れる🗺️🐳​

まずは5分で状況把握セット⏱️👀✨（ここが最重要）​

① docker compose ps：今“生きてる？”を一発確認🧟‍♂️✅​

② docker compose logs：原因はだいたいログにいる🪵🔥​

③ docker compose events：再起動ループとか“挙動”を掴む🔁👂​

④ docker compose config：YAMLの“最終形”を出して答え合わせ🧩✅​

⑤ docker compose exec：現場（コンテナ内）に入り込む🔦🕵️​

切り分けの“型”📐✨（これで迷子にならない）​

ハンズオン：DB接続不良を追う（API/DB/設定の切り分け）🧪🔥​

0) わざと失敗を仕込む😈（学習は再現が9割）​

1) 起動して、まず ps 👀​

2) logs：API側の“最初の例外”を拾う🪵🔍​

3) logs：DB側も見て「DBは元気？」を確認🩺​

4) exec：api コンテナの中で“事実確認”🔦​

5) 解決：接続先を db に直す✅✨​

“起動順/DB準備できてない問題”もついでに潰す🧯✨​

例：db に healthcheck を入れて、api は healthy 待ちにする🫶​

さらに強い技：デバッグ専用サービスを“必要な時だけ”起動する🧰✨​

Composeデバッグでよくある罠ランキング🪤🏆​

1位：直したのに反映されてない（restart しただけ）😵​

2位：孤児コンテナ（昔のサービスが残ってる）👻​

3位：ボリューム消して、データも消えた😭​

AI活用（そのままコピペでOK）🤖✨​

ログ解析プロンプト🪵​

Compose診断プロンプト🧩​

再発防止プロンプト🛡️​

ミニ課題🎒✨（5〜15分）​

まとめ🏁🎉​