Docker Composeで開発環境を統一する方法【チーム開発の悩みを解決】

「自分のPCでは動くのに、他のメンバーの環境では動かない」——チーム開発でこんな経験はありませんか？

このいわゆる "It works on my machine"問題 は、開発チームが抱える永遠の悩みのひとつです。今回はその解決策として非常に有効な Docker Compose を使った開発環境統一の方法を、実践的なサンプルを交えて解説します。

Docker Composeとは？

Docker Composeは、複数のDockerコンテナを一括で定義・管理するためのツールです。Webサーバー、アプリケーションサーバー、データベースなど、複数のサービスを docker-compose.yml という1つのファイルで定義することができます。

コマンド1つで全サービスを起動・停止できるため、環境構築の手順を劇的にシンプルにできます。

なぜ開発環境の統一にDocker Composeが有効なのか

環境差異をコードで管理できる

docker-compose.yml はテキストファイルなので、Gitで管理できます。つまり 「環境構築手順書」そのものをバージョン管理できる ということです。新メンバーがジョインしてもリポジトリをクローンしてコマンドを叩くだけで、同じ環境が手に入ります。

OS依存の問題を排除できる

WindowsでもMacでもLinuxでも、Dockerさえ動いていれば同じコンテナが動作します。「自分はMacだからHomebrewでインストールして…」といった環境ごとの手順書を書く必要がなくなります。

本番環境との差異を最小化できる

本番環境と同じDockerイメージを使うことで、「ローカルでは動くけど本番では動かない」という問題も軽減できます。

実践：Webアプリ開発環境をDocker Composeで構築する

ここでは Node.js + PostgreSQL の構成を例に、実際の docker-compose.yml の書き方を紹介します。

ディレクトリ構成

my-app/
├── docker-compose.yml
├── .env
├── app/
│   ├── Dockerfile
│   ├── package.json
│   └── src/
└── db/
    └── init.sql

docker-compose.yml の作成

version: '3.9'

services:
  app:
    build:
      context: ./app
      dockerfile: Dockerfile
    container_name: my_app
    ports:
      - "3000:3000"
    volumes:
      - ./app:/usr/src/app
      - /usr/src/app/node_modules
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgresql://user:password@db:5432/mydb
    depends_on:
      db:
        condition: service_healthy
    command: npm run dev

  db:
    image: postgres:15
    container_name: my_db
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: mydb
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./db/init.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d mydb"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:

app/Dockerfile の作成

FROM node:20-alpine

WORKDIR /usr/src/app

COPY package*.json ./
RUN npm install

COPY . .

EXPOSE 3000
CMD ["npm", "run", "dev"]

環境変数を .env で管理する

パスワードなどの機密情報は .env ファイルに切り出し、.gitignore に追加しておきましょう。

POSTGRES_USER=user
POSTGRES_PASSWORD=password
POSTGRES_DB=mydb

docker-compose.yml 内で ${POSTGRES_USER} のように参照することで、ファイルをGitにコミットしても安全です。

日常的に使うコマンド集

# コンテナのビルドと起動（バックグラウンド）
docker compose up -d --build

# コンテナの状態確認
docker compose ps

# ログの確認（リアルタイム）
docker compose logs -f app

# コンテナ内でコマンドを実行
docker compose exec app sh

# コンテナの停止と削除
docker compose down

# ボリュームも含めて完全にリセット
docker compose down -v

チーム運用のベストプラクティス

README.mdに起動手順をまとめる

docker compose up -d だけで動くとしても、前提条件（Dockerのバージョンなど）はREADMEに明記しておきましょう。

## セットアップ

1. `.env.example` をコピーして `.env` を作成する
2. `docker compose up -d --build` を実行する
3. `http://localhost:3000` にアクセスする

.env.example をGit管理する

.env はGitに含めず、.env.example（値を空にしたサンプル）だけをコミットします。これにより新メンバーが何を設定すべきか一目でわかります。

ホットリロードを活用する

上記の volumes 設定でローカルのファイルをコンテナにマウントしているため、コードを編集すると即座にコンテナ内に反映されます。npm run dev（nodemonなど）と組み合わせれば、コンテナを再起動せずに開発できます。

まとめ

Docker Composeを導入することで得られるメリットを改めて整理します。

課題	Docker Composeによる解決
環境差異による動作不具合	コンテナで環境を統一
新メンバーの環境構築コスト	コマンド1つでセットアップ完了
複数サービスの管理が煩雑	1ファイルで一元管理
本番との差異	同じイメージを使用可能

最初の設定には少し時間がかかりますが、一度整えてしまえば チーム全員が恩恵を受け続けられます。ぜひ今日のプロジェクトから導入してみてください。

doodle-on-web

自分で調べたことや、仕事の中で質問されたことなどをまとめています。