Docker Composeの設定と確認手順｜compose.yaml・config・upの使い方
Docker Composeの設定を新規作成・変更する際に、構文検証、環境変数、ポート公開、永続データ、変更後の確認を段階的に行うための作業ガイドです。基本操作の一覧ではなく、設定の品質と反映判断に重点を置きます。
この記事の目的
compose.yamlがどのコンテナ・ポート・ボリュームを管理するか確認し、構成と反映影響を分けて判断します。
最初にやること
docker context showとプロジェクトの作業ディレクトリを確認してから、docker compose config -qで検証します。
up -dはコンテナを再作成する場合があります。downは単なる停止ではなく削除操作です。web01などのコンテナ名、Composeサービス名・ポートは例です。Docker context・ホスト・保存先を実環境で確認してください。関連するガイド
Dockerの基本操作ガイド
コンテナの状態確認、起動・停止、接続先の基本操作へ戻ります。
記事を読む →DockerDockerコンテナ起動失敗
Exited・Restarting・OOMKilledなどの終了原因を切り分けます。
記事を読む →DockerDockerログ確認・容量対策
docker logsとログドライバー、保存容量の設計を確認します。
記事を読む →1. compose.yamlで指定するもの
Composeのservicesはサービスの実行定義、portsはホスト公開、volumesは永続データの保存先を扱います。environmentはコンテナに渡す設定値です。
例は検証用です。イメージのタグは必要に応じdigest固定を検討し、公開ポートは127.0.0.1に限定しています。本番ではセキュリティ要件・依存サービス・データ保存先を確認します。
127.0.0.1指定だけで完全に隔離されると判断せず、Engineのバージョン・ホストのネットワーク・Firewallを確認してください。Docker公式の注意事項を参照。2. 適用前の検証コマンド
config -qは設定の検証であり、サービスを起動しません。ただし構文が妥当でもアプリが起動できるとは限りません。未定義変数は警告のうえ空文字へ置換される場合があります。終了コードが0でも、警告の有無、展開後の設定値、対象プロジェクトを確認してください。必須の変数にはComposeの必須値構文を利用できます。configは環境変数が展開された内容を出すため、CIログやチケットでの秘匿値露出に注意。
3. .env・env_file・環境変数の違い
| 要素 | 役割 | 見落としやすい点 |
|---|---|---|
.env | Composeファイルの変数補間等に利用される | 自動的に全変数がコンテナ環境へ渡るわけではない |
env_file | サービスのコンテナ環境変数を渡す | ファイルの相対パス・参照元・機密性 |
environment | サービスに明示する環境変数 | 値の優先順位や補間を確認 |
docker compose configの出力も公開しないようにします。補間時に必要な変数を強制する構文や、変数の優先順位はDocker公式の変数補間仕様を参照。docker compose configの展開結果は機密情報を含む場合があるため、そのまま公開しないでください。
4. up・start・stop・downの違い
| コマンド | 主な作用 | 影響 |
|---|---|---|
docker compose up -d | サービス作成・起動、必要なら再作成 | 再起動・構成変更の影響があり得る |
docker compose start | 既存の停止済みコンテナを起動 | 新しい設定を反映する方法ではない |
docker compose stop | コンテナの停止 | コンテナは通常保持される |
docker compose down | コンテナと対象ネットワークの削除 | 匿名volumeの再利用等に注意 |
docker compose down -v | さらに対象ボリュームを削除 | 永続データ消失のおそれ |
down -vを業務サービスの停止手段として使わないでください。保存データ・復旧方法を確認する必要があります。5. 変更証跡と切り戻し可否の事前監査
実行前に「対象・変更前・変更後・復旧可否」を同じ作業記録に残します。構成管理されたCompose定義や変数の管理元の版、使用イメージのdigest、サービス名、ポート、Volume、依存サービスを記録してください。環境変数の実値や展開済み設定には秘匿情報が含まれるため、チケットやログへ無加工で保存しません。
| 更新前の判断 | 実施・復旧条件 |
|---|---|
| 旧イメージ・旧設定を再取得可能、永続データ互換性を確認済み | 承認済み手順で反映。障害時は管理元の旧定義と旧イメージ参照へ戻し、再作成後に業務疎通・ログ・データを再確認 |
| DB移行・データ形式変更を伴う | 設定だけ戻しても復旧できない可能性。DB固有のバックアップと復元リハーサルが完了するまで更新を保留 |
| 旧イメージが取得不可、管理元の版・変数が不明 | 切り戻し不能の可能性があるため変更を保留し、必要な成果物を確保 |
| 更新後にrunningだがヘルス・通信・業務処理が異常 | 未完了と判定。ログと変更差分を保全し、復旧計画に従って対応 |
運用中サービスを再作成する前に、レジストリから旧イメージを確実に取得できるかも確認します。docker compose down -vは切り戻し手段ではありません。
6. 実行・確認の流れ
構文検証成功とサービスの正常性は別です。状態・ログ・ヘルスチェック・クライアントからの実通信を確認します。
7. 想定と違うとき
| 状態 | 確認するもの |
|---|---|
| 変数が空・設定を読めない | Composeの実行ディレクトリ、指定ファイル、変数補間 |
| ポートがバインドできない | ホストのss -lnt、使用ポート、公開先 |
| コンテナがすぐに終了 | Dockerコンテナ起動失敗の切り分け |
| ログが見えない | Dockerログドライバーと容量対策 |
切り戻しは前のComposeファイル・イメージ・変数・データ互換性を確保する作業です。downとupだけで元に戻るとは限りません。
関連する確認手順：Volumeのバックアップ・復元。
8. 設定検証の結果から次の作業を決める
構文検証の成功はアプリの起動成功を意味しません。以下はCompose V2系を想定した手順です。変更するプロジェクト・ファイル・公開範囲を先に確認してください。
| 表示・結果 | 読み方 | 次の行動 |
|---|---|---|
config -q成功、通常は無出力 | Compose構成の検証を通過 | サービス名・公開ポート・Volume・反映影響を点検し、承認後に変更 |
services.web等の設定エラー | キーやインデントなどが不正の可能性 | エラーの該当行を修正し再度config -q。失敗中はupを実行しない |
| 変数未定義警告・想定外の補間 | .env・env_file・環境変数の管理元に不一致 | 変数の設定元を確認。docker compose configは機密値を含むため共有しない |
dry-runでRecreateと表示 | 変更時にコンテナの入れ替えが起こる可能性 | 停止許容時間、保持データ、アプリの接続中ユーザー、切り戻し手順を確認 |
| 構文は正常だが起動直後に停止 | アプリ設定や実行環境などの別の問題 | コンテナ起動失敗の切り分けへ進む |
9. 反映・切り戻し・完了確認
以下はこの記事の検証用nginxサービスを対象とした例です。作業前にイメージのタグ/digest、Compose定義、変数、Volume、業務影響、戻すべき旧構成を管理元に記録してください。
| 確認結果 | 完了条件・次の行動 |
|---|---|
| コンテナがrunningでHTTPも期待どおり応答 | nginxの検証例では成功候補。業務アプリならヘルスチェック・依存先・本来の業務機能まで確認 |
| Exited/Restartingになった | 不合格。直前ログを保存し、起動失敗の原因調査へ進む |
| 起動したが通信できない | 公開ポート、アプリ側のlisten、Proxy・Firewallを確認。up -d成功だけでは完了にしない |
| 更新後に業務不具合 | 保存した旧Compose定義・イメージ参照・変数へ管理元から戻す計画を判断。データ移行済みならDB・Volumeの互換性を別途確認 |
down -vで元へ戻すことはできません。旧設定へ戻して再適用する際にもコンテナ置換・DB互換性・業務停止の影響があります。