Docker・インフラ構築についてよくある質問

こうした問題は、Dockerそのものが難しいというより、確認する順番が決まっていないことから起きる。

個人開発では、Laravelのコードを書いている時間より、環境の状態を確認している時間のほうが長くなる瞬間がある。私も、機能追加の仮説検証を進めたいのに、原因不明の接続エラーや停止したコンテナに足を取られてきた。ユーザーの痛みを解消する前に、開発者自身の環境が痛み始める。かなり厄介な構造だ。

Dockerのインフラ構築で必要なのは、いきなり設定ファイルを読み解くことではない。まず現在の状態を一覧で確認し、次に詳細を掘り、最後にリソースとデータの持ち方を確認すること。この順番だけで、調査の迷走はかなり減らせる。

Dockerのトラブル調査は、推測から始めない。まず「今、何が動いているか」を事実として見る。

まず確認したいのは、コンテナが本当に動いているか

Docker環境の調査で、最初に実行するコマンドはほぼ決まっている。

docker ps

このコマンドを実行すると、現在稼働しているコンテナの一覧が表示される。確認できる主な情報は、コンテナ識別子、使用しているイメージ、実行中のコマンド、作成時刻、状態、ポートの対応関係、コンテナ名だ。

Laravelの開発環境であれば、アプリケーション、ウェブサーバー、データベース、キャッシュサーバーなど、複数のコンテナが並ぶことが多い。ここで確認したいのは、単に一覧が表示されるかではない。

• Laravelのアプリケーション用コンテナが起動しているか
• ウェブサーバーが起動しているか
• データベース用コンテナが起動しているか
• ホスト側のポートとコンテナ側のポートが意図どおり対応しているか
• 状態が継続して「Up」になっているか
• 再起動を繰り返していないか

たとえば、ウェブサーバーのコンテナだけ起動していて、データベースのコンテナが一覧に出てこない場合、ブラウザからLaravelへアクセスできても、ログインや一覧取得の段階で失敗する。画面が表示されるかどうかだけを見ていると、問題の位置を誤る。

停止したコンテナも含めて確認する

docker ps は、基本的に稼働中のコンテナを確認するコマンドだ。停止したコンテナまで見たい場合は、次を使う。

docker container ls -a

または、短縮形として次のコマンドも利用できる。

docker ps -a

ここで状態を確認すると、調査の手がかりが増える。たとえば、状態欄に次のような違いが出る。

• Up：現在起動している
• Exited：プロセスが終了し、コンテナも停止している
• Created：作成されたが、まだ起動していない
• 再起動を示す状態：起動後すぐに終了する問題が疑われる

Exited になっているコンテナがあれば、そこで初めてログを確認する。起動していないものを、ネットワークやブラウザの問題だと決めつけない。ここが調査の分岐点になる。

ポート番号は「公開」と「内部通信」を分けて考える

Dockerのポート表示は、慣れるまで少し混乱する。

たとえば、次のような表示があるとする。

0.0.0.0:8080->80/tcp

これは、ホスト側の8080番ポートへのアクセスを、コンテナ側の80番ポートへ転送しているという意味だ。ブラウザからアクセスする場合は、ホスト側の8080番ポートを使う。

一方、コンテナ同士の通信では、ホスト側の公開ポートを経由しない構成が一般的だ。Docker Composeで同じネットワークに接続されたアプリケーションコンテナからデータベースへ接続するなら、接続先にはデータベースのサービス名を使う。ホスト側へ公開するためのポート番号と、コンテナ間通信で使う宛先を同じものとして扱うと、接続エラーが起きやすい。

この違いは、Laravelの環境変数を設定するときに特に表れる。

• ブラウザからLaravelへアクセスする場合：ホスト側に公開したポート
• Laravelからデータベースへ接続する場合：データベースのサービス名と内部ポート
• ホストマシンからデータベースへ接続する場合：ホスト側へ公開したポート

「ポートは開いているのに接続できない」という場合、ポートの有無ではなく、どの場所からどの場所へ接続しているのかを整理する必要がある。

コンテナの詳細を調べるなら docker inspect

一覧表示で状態が分かっても、原因までは分からない。次に使うのが docker inspect だ。

docker inspect コンテナ名

このコマンドでは、コンテナやイメージに関する低レベルの詳細情報を、JSON形式で取得できる。コンテナの設定、マウント、ネットワーク、環境変数、起動コマンド、再起動設定など、一覧表示では見えない情報を確認できる。

ただし、最初から出力全体を読む必要はない。情報量が多いため、目的を決めずに実行すると、調査がかえって散らかる。仮説に合わせて必要な値を絞るのがコツだ。

コンテナのIPアドレスを確認する

コンテナのIPアドレスを取得したい場合は、--format オプションを組み合わせる。

docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' コンテナ名

このコマンドで、接続しているネットワーク上のIPアドレスを抽出できる。

ただし、アプリケーションの接続先としてIPアドレスを直接書く設計は、個人開発のローカル環境でも慎重に扱いたい。コンテナを再作成したとき、IPアドレスが変わる可能性があるためだ。Docker Composeのサービス名で名前解決できる構成なら、固定のIPアドレスに依存しないほうが運用しやすい。

ここでの docker inspect の目的は、常にIPアドレスを探すことではない。ネットワークへ参加しているか、どのネットワークに接続しているか、想定した設定が反映されているかを確認することにある。

マウントとボリュームを確認する

Dockerでデータが消える問題を調査するとき、最初に見るべき場所のひとつがマウント設定だ。

docker inspect コンテナ名

出力内の Mounts を確認すると、コンテナ内のディレクトリがどのボリュームやホスト側ディレクトリに接続されているかを把握できる。

Laravelであれば、次のようなデータが関係する。

• データベースのデータディレクトリ
• アップロードされた画像やファイル
• アプリケーションのストレージ領域
• ログをホスト側へ保存する設定
• 開発中のソースコードを反映するバインドマウント

コンテナの中にファイルが存在するからといって、そのデータが永続化されているとは限らない。コンテナを削除しても残る場所に保存されているのか、それともコンテナの書き込みレイヤーにだけ存在するのか。この違いが重要だ。

環境変数を抽出して設定の食い違いを探す

データベース接続エラーでは、Laravel側の設定とデータベース側の設定が一致していないケースが多い。

docker inspect --format='{{range .Config.Env}}{{println .}}{{end}}' コンテナ名

これで、コンテナへ渡されている環境変数を確認できる。

確認する項目は、たとえば次のようなものだ。

• データベースのホスト名
• データベース名
• ユーザー名
• パスワード
• 接続ポート
• アプリケーションの実行環境
• キャッシュやキューの接続先

ここで注意したいのは、パスワードなどの機密情報が表示されることだ。画面共有やログへの貼り付けを行うときは、値をそのまま公開しない。調査のためのコマンドが、別のセキュリティ事故を生まないようにする。

ログは「失敗した瞬間」を確認するために使う

コンテナの状態が Exited なら、次にログを見る。

docker logs コンテナ名

Docker Composeを使っている場合は、プロジェクトの構成に応じて、サービス単位でログを確認することもできる。

ログを見るときに、最初から最後まで読もうとすると時間がかかる。見るべきなのは、起動直後のエラーと、最後に記録された終了直前のメッセージだ。

起動直後に落ちる場合

起動直後にコンテナが停止する場合、次のような原因が考えられる。

• 実行対象のファイルが存在しない
• 環境変数が不足している
• 設定ファイルの構文に問題がある
• ポートがすでに別のプロセスで使用されている
• データベースの初期化に失敗している
• 権限不足でディレクトリへ書き込めない
• イメージに必要な実行ファイルが含まれていない

ここで大切なのは、エラーメッセージを読んだ瞬間に設定をいじり始めないことだ。

まず、仮説を一つに絞る。次に、その仮説を確認できる情報を探す。設定変更はそのあとだ。原因を特定しないまま複数箇所を変更すると、ビフォーアフターの比較ができなくなる。

個人開発では、この比較可能性がかなり重要になる。仮説検証を進めるための環境なのに、変更履歴が分からなくなると、何が効いたのか判断できない。

ログが少ない場合の見方

ログがほとんど出ない場合もある。アプリケーションのログが標準出力へ流れていない、ログファイルがコンテナ内部に保存されている、ウェブサーバーとアプリケーションのログを別々に確認する必要がある、といった構成だ。

このときは、次の観点でログの出力先を確認する。

• ウェブサーバーのアクセスログ
• ウェブサーバーのエラーログ
• PHPの実行ログ
• Laravelのアプリケーションログ
• データベースの起動ログ
• Docker Composeを起動したターミナルの出力

ブラウザに500番台のエラーが表示されても、原因がLaravel本体とは限らない。ウェブサーバーがPHPへ処理を渡せていない可能性もあるし、Laravelがデータベースへ接続できていない可能性もある。

画面に出た症状と、実際に失敗したレイヤーは別だ。ここを混同しないだけで、調査の精度が上がる。

docker container stats でリソースの偏りを見る

アプリケーションが起動しているのに遅い。一定時間動かすと応答しなくなる。ビルドやテストの途中で処理が止まる。

こうした場合は、コンテナのリソース使用状況を確認する。

docker container stats

このコマンドでは、稼働中コンテナのCPU使用率、メモリ消費量、ネットワーク入出力量、ブロック入出力量などをリアルタイムで確認できる。

CPU使用率やメモリ使用量の絶対値だけを見て、すぐに良し悪しを決めるものではない。見るべきなのは、どのコンテナが相対的に負荷を持っているか、負荷が一時的なのか継続的なのか、処理の実行と負荷の上昇が対応しているかだ。

Laravel環境で負荷が偏りやすい場所

個人開発のLaravel環境では、次のような処理で負荷が上がることがある。

• 依存パッケージのインストール
• フロントエンド資産のビルド
• 大量データを扱うマイグレーション
• キュー処理
• 定期的なバッチ
• キャッシュの再生成
• ログやアップロードファイルの処理
• データベースのインデックス作成

たとえば、画面表示が遅いからといって、ウェブサーバーだけを調整しても、実際にはデータベースコンテナのCPU使用率が上がっているかもしれない。逆に、データベースに問題があるように見えて、実はアプリケーションコンテナがメモリ不足になっていることもある。

ユーザーの反応を見ていると、遅い画面に対する不満は、機能そのものへの不満より早く表面化する。機能の仮説検証が進んでいても、応答速度が悪ければコンバージョンにつながらない。インフラの状態確認は、技術者の自己満足ではなく、プロダクトの体験を守る作業だ。

リソース確認は一度だけで終わらせない

docker container stats は、その瞬間の状態を確認するためのコマンドだ。長期的な監視の代わりではない。

ただ、障害の切り分けでは十分に役に立つ。

1. 問題が起きていないときの状態を見る

2. 重い処理を実行する

3. コンテナごとの負荷の変化を見る

4. 処理が終わったあとに負荷が戻るか確認する

5. 再現条件と負荷の関係を記録する

この流れで見れば、単なる印象ではなく、処理とリソースの関係を検証できる。

CPU使用率が一時的に上がるだけなら、ビルド処理として許容できるかもしれない。一方で、処理終了後もメモリ使用量が戻らないなら、キャッシュやワーカープロセスの状態を確認したほうがよい。

ここでも、根拠のない成功法則は役に立たない。「メモリはこの値以下なら安全」といった一律の基準を置くのではなく、アプリケーションの処理内容と、実際の応答状況を並べて見る。

ディスク容量は docker system df で確認する

Dockerを使い続けていると、ディスク容量が少しずつ減っていく。イメージを何度もビルドし、不要なコンテナを作り、ビルドキャッシュが積み上がる。個人開発では、環境を壊したくない気持ちから、古いものを残したままにしがちだ。

ディスクの使用状況を確認するには、次のコマンドを使う。

docker system df

このコマンドでは、次のようなDocker関連データの使用量をまとめて確認できる。

• イメージ
• コンテナ
• ローカルボリューム
• ビルドキャッシュ
• 再利用可能な容量

削除を実行する前に、まず現状を見る。これが基本だ。

イメージが増え続ける理由

Dockerfileを修正して何度もビルドしていると、イメージや中間レイヤーが増えることがある。マルチステージビルドを使う場合でも、ビルド用の依存関係と実行用の構成を適切に分けなければ、最終イメージが大きくなる。

ただし、イメージが大きいから即座に失敗というわけではない。問題は、ビルド時間、デプロイ時間、ディスク使用量、脆弱性管理、起動時間など、プロダクト運用へどの負担を生んでいるかだ。

個人開発では、最初から完璧なDockerfileを目指すより、まず動く構成を作り、実際の開発フローでボトルネックを測ったほうがよい。ビルドが遅い、CIでキャッシュが効かない、本番への転送に時間がかかる。そうした痛みが見えてから、マルチステージビルドやレイヤー構成を改善する。

ボリュームの容量は特に慎重に扱う

ローカルボリュームには、データベースのデータやアップロードファイルが保存されている可能性がある。不要に見えるボリュームを削除すると、開発データや検証データを失うことがある。

Dockerコンテナは基本的にステートレスだ。ボリュームやバインドマウントを設定せず、コンテナ内部へ保存したデータは、コンテナを削除すると失われる。

ここはDockerを使い始めた人が最も誤解しやすい部分だ。

開発環境では、データを残したいものと、壊しても作り直せるものを分ける。データベースの中身を毎回作り直せるなら、ボリュームの扱いは比較的シンプルになる。検証ユーザーやテストデータを残したいなら、削除操作の前に保存場所を確認する必要がある。

コンテナを再作成できる設計と、データを再作成できる設計は別物。ここを一緒にすると、復旧時に必ず迷う。

Docker Composeの状態を確認するときの順番

複数のコンテナを使うなら、Docker Composeの構成全体を確認する必要がある。Laravel、ウェブサーバー、データベース、キャッシュ、メール確認用サービスなどを個別に見ていると、サービス間の依存関係を見落としやすい。

調査の順番は、次のようにすると安定する。

1. サービス一覧と状態を見る

まず、稼働中のコンテナを確認する。

docker compose ps

停止したサービスも含めて確認したい場合は、環境に応じて全コンテナを表示する。

docker compose ps -a

ここで見るのは、サービス名、状態、ポート、再起動の有無だ。

2. 依存するサービスから確認する

Laravelがデータベースへ接続できない場合、Laravelの設定だけを見るのではなく、データベースコンテナが起動しているか、起動後に初期化を完了しているかを見る。

調査の基本的な順番は次のとおりだ。

1. データベースやキャッシュなど、依存先のコンテナが起動しているか確認する

2. 依存先のログで初期化エラーがないか確認する

3. アプリケーションコンテナの環境変数を確認する

4. サービス名、ポート、認証情報の対応を確認する

5. アプリケーション側のログで接続エラーを確認する

6. 必要であればネットワーク設定を確認する

アプリケーションから見た接続先と、ホストから見た接続先は異なる場合がある。ここを分けて確認するだけで、誤ったポートへ接続し続ける時間を減らせる。

3. ネットワークの名前だけで判断しない

サービスが同じComposeプロジェクトに含まれていても、意図したネットワークに接続されているとは限らない。設定変更の途中でネットワークを分けた、別プロジェクトとして起動した、古いコンテナが残っているといった状況では、名前解決や通信経路が期待どおりにならないことがある。

docker inspect で各コンテナのネットワーク情報を確認し、どのネットワークへ参加しているかを照合する。

ここでIPアドレスだけを見て終わらせないこと。サービス名、ネットワーク名、接続先、公開ポートを一緒に見る。インフラの問題は、一つの値だけでは判断できない。

「起動しているのに使えない」問題の切り分け

Dockerの調査で特に時間を消費するのが、状態としては起動しているのに、アプリケーションが使えないケースだ。

この場合、まず症状を分解する。

ブラウザからアクセスできない

確認する順番は、次のようになる。

• ウェブサーバーのコンテナが起動しているか
• ホスト側のポートが公開されているか
• ブラウザでアクセスしているポートが正しいか
• ウェブサーバーのエラーログに異常がないか
• アプリケーションコンテナとの通信設定があるか
• Laravelのルーティングやアプリケーションログに問題がないか

ブラウザに接続拒否が出る場合と、Laravelのエラーページが表示される場合では、失敗している場所が違う。

接続拒否なら、ポート公開やプロセス起動の問題を疑う。エラーページまで到達しているなら、Dockerの外側ではなく、ウェブサーバーからLaravelへ渡った後の処理を調べる。

データベースへ接続できない

データベース接続では、次の組み合わせを確認する。

データベースコンテナを再作成したあとに、初期化用の環境変数を変更しても、既存ボリューム内のデータベース設定がそのまま残っていることがある。設定ファイルの現在値だけを見ると、実際の状態と一致しない。

この場合は、環境変数、ボリューム、データベースの初期化状態を分けて確認する必要がある。

ファイルが反映されない

開発中にソースコードを変更したのに、ブラウザへ反映されない場合は、バインドマウントやキャッシュを確認する。

• ホスト側のソースコードがコンテナへマウントされているか
• マウント先のディレクトリが正しいか
• コンテナ内で古いファイルを参照していないか
• PHPやフレームワーク側のキャッシュが残っていないか
• フロントエンドのビルドが必要な構成になっていないか

ここでも、コンテナが起動しているかどうかだけでは判断できない。起動状態は正常でも、開発ファイルが別のディレクトリへマウントされている可能性がある。

個人開発では、環境の便利さと、仕組みの見えにくさが表裏一体になる。ファイルを保存するだけで反映される環境は快適だが、その裏側でどのディレクトリが共有されているのかを把握していないと、障害時に手が止まる。

Dockerfileやイメージの確認で見るべきポイント

コンテナの状態に問題がなくても、イメージの作り方に無駄があると、開発体験とデプロイ速度が悪化する。

Dockerfileを改善するとき、最初に見るべきなのは「どれだけ高度な最適化をしているか」ではない。必要なファイルだけが入り、再利用できるレイヤーが活用され、実行時に不要なものを含めていないかだ。

依存関係のインストールを毎回やり直さない

Dockerfileでは、変更頻度の低いファイルを先にコピーし、依存関係のインストールをキャッシュしやすくする構成がよく使われる。

Laravelであれば、依存パッケージの定義ファイルと、頻繁に変更されるアプリケーションコードを同じ順番で扱うと、コードを一行変更しただけで依存関係のインストールからやり直すことになる。

この差は、開発初期には小さく見える。しかし、検証回数が増えるほど効いてくる。コンバージョン改善の仮説を一つ試すたびにビルドを待つ環境では、試行回数そのものが減る。

技術的な最適化は、開発者の気持ちよさだけを目的にしない。仮説検証のサイクルを短くし、ユーザーの反応へ早く到達するために行う。

マルチステージビルドは目的を持って使う

マルチステージビルドでは、ビルドに必要なツールや依存関係を含む段階と、実際にアプリケーションを実行する段階を分けられる。最終イメージを小さくしやすく、実行時に不要なものを持ち込まずに済む。

ただし、導入すれば必ず正解というわけではない。

• ローカル開発用と本番用で必要なファイルが違う
• ビルド成果物の受け渡しが分かりにくくなる
• 開発時のデバッグが難しくなる
• 依存関係の境界を誤ると、実行時に必要なファイルが欠ける

まずは開発環境と本番環境の目的を分ける。開発環境は変更を反映しやすいこと、本番環境は再現性と不要な依存関係の少なさを優先すること。この違いを一つのDockerfileですべて解決しようとすると、構成が複雑になりやすい。

よくある確認ミスと、調査を止めないための考え方

docker ps だけ見て安心する

稼働中のコンテナが表示されていても、アプリケーションが正常に動いているとは限らない。プロセスが起動していても、データベース接続に失敗していることはある。

docker ps は入口だ。そこで終わらず、必要に応じてログ、詳細情報、リソース使用量へ進む。

docker inspect の出力を全部読む

詳細情報は強力だが、量が多い。目的のない確認は、情報を増やすだけになる。

IPアドレスを見たいのか、マウントを見たいのか、環境変数を見たいのか。仮説に応じて --format で必要な情報を絞る。

いきなりコンテナを削除する

再作成で直る問題もある。しかし、データの保存場所を確認せずに削除すると、原因を消すだけでなく、データそのものを失うことがある。

削除前に、次の情報を残しておく。

• コンテナの状態
• 関連するログ
• マウント情報
• ボリューム名
• 環境変数の構成
• 実行していたコマンド
• 再現条件

失敗した状態は、次の改善に使える。消す前に観測する。

ホスト側とコンテナ側の視点を混ぜる

ホストから接続するのか、コンテナから接続するのかで、使うポートやホスト名が変わる。これを混ぜると、設定の修正を繰り返すことになる。

接続元と接続先を紙やメモに書くだけでもよい。複雑な図は必要ない。どのプロセスが、どの名前とポートへ接続しているのかを分けるだけで、調査の精度は上がる。

データを永続化したつもりになる

コンテナが停止しても、データが残るとは限らない。ボリュームやバインドマウントの設定がなければ、コンテナ内部のデータは削除時に失われる可能性がある。

本番環境では、ボリュームを設定しただけでバックアップが完了するわけでもない。永続化、バックアップ、復元テストは別の問題だ。

状態確認のために覚えておきたいコマンド

最後に、Dockerのインフラ構築で状態確認に使うコマンドを、目的別に整理しておく。

コマンドを暗記すること自体が目的ではない。状態確認の順序を持っておくことが目的だ。

1. 何が起動しているかを見る

2. 停止したものがないかを見る

3. ログで失敗箇所を特定する

4. 詳細設定でネットワークやマウントを確認する

5. リソース使用量を確認する

6. ディスクとデータ保存の状態を見る

この順番なら、問題を「Dockerが動かない」という大きな塊のまま扱わずに済む。

まとめ：Dockerの確認は、プロダクトの検証速度を守る作業

Docker・インフラ構築についてよくある質問の多くは、実は「どのコマンドを使うか」より、「どの順番で状態を見るか」に集約される。

docker ps で稼働中のコンテナを確認し、docker container ls -a で停止したコンテナまで見る。問題があれば docker logs で失敗の瞬間を探す。設定やネットワーク、マウントの状態は docker inspect で掘る。動いているのに遅いなら docker container stats、ディスクが減っているなら docker system df を使う。

そして、データを残したいなら、ボリュームやバインドマウントを明示的に設計する。コンテナの再作成とデータの再作成は、別の話として扱う。

インフラの確認は、アプリケーション開発から離れた作業に見える。しかし、環境が不安定なら、仮説を試す回数が減る。ユーザーの反応を受けて改善するまでの時間が伸びる。結果として、機能の価値を検証する前に、開発の流れが止まる。

だから私は、Dockerの状態確認を単なる保守作業とは考えていない。ユーザーの痛みへ近づくための、プロダクト開発の一部だ。

次に試したいことは、状態確認のコマンドを手順書へまとめるだけではない。Laravelの開発環境で、起動状態、ログ、リソース、ディスク使用量を一度に把握できる確認フローを作り、初めて触る人でも同じ切り分けができるようにすること。個人開発の速度は、コードを書く速さだけで決まらない。迷ったときに、どれだけ早く事実へ戻れるかで決まる。

Related reading: Docker・インフラ構築をわかりやすく解説 and Docker導入の分岐点：個人開発でコンテナ化が必要になる基準.