Docker Compose環境切り替えのベストプラクティス

複数のDocker Compose環境を切り替えるにあたっての基本認識

複数のDocker Compose環境を効率的に管理するには、開発・本番環境の差異に対応する仕組みとファイル管理の工夫が不可欠です。特にWeb開発では、環境ごとの設定違い（例：データベースURLやAPIキー）が頻繁に生じますが、これらを手動で調整するのは誤りのリスクが高まります。また、同じリポジトリ内で複数の環境を構築する場合、ファイル構成の明確化が効率性と保守性を大きく左右します。以下では、こうした課題に対応する具体的なアプローチを解説します。

複数YAMLファイルを指定する方法

Docker Composeは-fオプションによって、複数のYAMLファイルを柔軟に指定できます。これにより、共通設定と環境固有設定を分離し、「一括管理」と「個別カスタマイズ」を両立させることが可能です。

複数環境用YAMLの作成ガイド

1. 共通設定ファイル（docker-compose.yml）

すべての環境で共通するサービス定義やネットワーク構成を記述します。たとえば、以下のような構造がおすすめです：

2. 環境固有設定ファイル（例: docker-compose.dev.yml, docker-compose.prod.yml）

開発・本番環境ごとに差分を記述します。例えば、ホストマウントやデバッグツールの追加などが該当します：

実行時の指定手順

• 環境ごとにコマンドを実行する場合:
  bash
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

• 短縮版（COMPOSE_FILE環境変数を使う）:
  bash
export COMPOSE_FILE=docker-compose.yml:docker-compose.dev.yml
docker-compose up

注意：docker-compose downはネットワークやボリュームを削除するため、デバッグ中のリソース保持が必要な場合は docker-compose stop を使用することを推奨します。

.envファイルで環境変数を一元管理する手法

.envファイルは、Docker Composeの設定ファイルと連携して利用できる重要なツールです。これにより、APIキーやデータベース接続情報などの機密情報を外部化し、リポジトリ内での扱いを統制できます。

.envファイルの構成例

以下のように、環境ごとに必要な変数を定義します：

環境ごとの変数切り替え手順

1. 対象環境の.envファイルをロード:
   bash
# 開発環境の場合
export COMPOSE_FILE=docker-compose.yml:docker-compose.dev.yml
docker-compose config --env-file .env.dev

2. 起動時の自動読み込み:
   Docker Composeは.envファイルを自動で読み込みます。ただしその際、COMPOSE_FILEで指定したYAMLファイルと合わせて使用する必要があります。

環境依存性の注意点：.envファイルの自動読み込みには、プロジェクトディレクトリの構造やOSのバージョンに依存する場合があります。手動で環境変数を設定することも検討してください。

docker-compose stopによるリソース制御のベストプラクティス

環境切り替え時にリソース競合や不具合を防ぐには、不要なコンテナやネットワークの停止が必須です。docker-compose stopと合わせた操作フローによって、安定した切り替えを実現します。

不要なコンテナの停止手順

1. 現在起動中のサービス一覧確認:
   bash
docker-compose ps

2. 特定環境のコンテナを停止:
   bash
docker-compose -f docker-compose.yml -f docker-compose.dev.yml stop

3. リソースリーク防止のために再起動時に--build指定:
   bash
docker-compose up --build

起動・停止時の注意点

• docker-compose downを使うと、ネットワークやボリュームも削除されるため、必要に応じて使い分ける
• 環境ごとにdocker-compose stopを実行しないと、 残ったコンテナが後続の起動に影響を与える可能性がある

COMPOSE_FILEの挙動に関する注意喚起: COMPOSE_FILEはデフォルトのYAMLファイルを上書きするため、複数環境で設定が一致しない場合にエラーが発生します。必ず事前に確認してください。

git-worktreeによるディレクトリ単位環境構築

同一リポジトリ内で複数の環境（開発・本番など）を分離するには、git worktreeが非常に有効です。これにより、それぞれに専用のDocker Compose設定ファイルや.envファイルを配置できるため、混乱を防ぎます。

ワークツリーの設定方法

1. ワークツリーを作成:
   bash
git worktree add ../dev_env dev_branch

2. 各ディレクトリに環境固有のファイルを配置:
   /project
├── .env.dev
├── docker-compose.yml
└── dev_env/
├── .env.prod
└── docker-compose.prod.yml

複数プロジェクトでの適用例

ディレクトリ構造の複雑化リスク: ワークツリーを多用するとプロジェクトディレクトリが増えるため、リポジトリ管理やバージョン制御において注意が必要です。定期的な整理が推奨されます。

実践的なファイル構成と環境切り替えワークフロー

効率的な開発には、プロジェクトディレクトリの設計と自動化スクリプトの活用が不可欠です。以下に具体的な例を示します。

プロジェクトディレクトリの設計例

自動化スクリプトの活用案

• 環境ごとの起動・停止を簡略化するシェルスクリプト:
  bash
# dev.sh
export COMPOSE_FILE=docker-compose.yml:docker-compose.dev.yml
docker-compose -f $COMPOSE_FILE up --build

• direnvでディレクトリごとに自動環境変数読み込み:
  .envrcに記述することで、ディレクトリ移動時に自動で.envファイルをロードできます。

補足とまとめ

今回の解説では、複数のDocker Compose環境切り替えに関する技術的側面と運用上の注意点を中心に整理しました。特に以下の点を意識してください：

• COMPOSE_FILE環境変数の使用には環境依存性があるため、手動確認が必要です
• docker-compose downはリソース削除を行うので、デバッグ目的ではstopを活用
• .envファイルの自動読み込みはプロジェクト構造に強く依存するため、事前テスト推奨
• git-worktreeによるディレクトリ分離は管理コストを増やす可能性がある

以上を踏まえ、開発・本番環境の切り替えを安定して実施してください。