Docker Composeで安全に環境別設定を共有する方法 – マイクロサービス実践ガイド

2026年4月27日

Contents

1 1️⃣ Docker Compose の概要と基本構文
- 1.1 最小構成例
2 2️⃣ マイクロサービス構成例 ― カスタムネットワークと名前解決
3 3️⃣ 環境別設定と .env 管理
4 4️⃣ ローカル開発での Ingress エミュレーション
5 5️⃣ 本番デプロイのベストプラクティス
- 5.1 5.1 deploy: セクションの正しい使い方
- 5.2 5.2 CI/CD パイプラインへの組み込み例
  - 5.2.1 GitHub Actions（.github/workflows/deploy.yml）
  - 5.2.2 GitLab CI（.gitlab-ci.yml）
6 6️⃣ まとめ ― 実務で役立つポイント

スポンサードリンク

1️⃣ Docker Compose の概要と基本構文

項目	内容
目的	複数コンテナを 1 つの YAML ファイルで定義し、`docker compose up` だけで一括起動・停止できる。
ファイル名	`docker-compose.yml` または拡張子が `.yaml/.yml` の任意の名前（例：`compose.yaml`）。
主要キー	`services`、`networks`、`volumes` などのトップレベルキーと、必要に応じて `configs`・`secrets`。
バージョン宣言	Compose Specification（2025 年版）では `version:` キーは省略可能。ただし古い Docker Engine と互換性を保ちたい場合は `"3.9"` などを書いてもよい。

公式情報: https://docs.docker.com/compose/

最小構成例

# compose.yaml（Compose Spec 2025 年版に準拠）
services:
  app:
    build: .
    image: myorg/app:latest
    ports:
      - &quot;8080:80&quot;
    environment:
      APP_ENV: development

# compose.yaml（Compose Spec 2025 年版に準拠）

services:

app:

build: .

image: myorg/app:latest

ports:

- "8080:80"

environment:

APP_ENV: development

build: と image: を同時に記述すると、docker compose up --build 時に自動でイメージがビルドされる。
ports: は ホスト:コンテナ の形式で公開ポートを指定し、environment: ではキーとバリューのマッピングを書ける。

2️⃣ マイクロサービス構成例 ― カスタムネットワークと名前解決

Docker Compose が提供する DNS 機能により、同一ネットワーク内のコンテナは サービス名 をそのままホスト名として参照できる。これを利用した典型的な 4 コンテナ構成を示す。

version: &quot;3.9&quot;

services:
  web:
    image: nginx:stable-alpine
    ports:
      - &quot;80:80&quot;
    depends_on:
      - app
    networks:
      - backend

  app:
    build: ./app
    environment:
      DATABASE_URL: postgres://db_user:secret@db:5432/app_db
      CACHE_HOST: cache
    networks:
      - backend

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: db_user
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app_db
    volumes:
      - pg_data:/var/lib/postgresql/data
    networks:
      - backend

  cache:
    image: redis:7-alpine
    networks:
      - backend

networks:
  backend:
    driver: bridge

volumes:
  pg_data:

version: "3.9"

services:

web:

image: nginx:stable-alpine

ports:

- "80:80"

depends_on:

- app

networks:

- backend

app:

build: ./app

environment:

DATABASE_URL: postgres://db_user:secret@db:5432/app_db

CACHE_HOST: cache

networks:

- backend

db:

image: postgres:15-alpine

environment:

POSTGRES_USER: db_user

POSTGRES_PASSWORD: secret

POSTGRES_DB: app_db

volumes:

- pg_data:/var/lib/postgresql/data

networks:

- backend

cache:

image: redis:7-alpine

networks:

- backend

networks:

backend:

driver: bridge

volumes:

pg_data:

depends_on: は起動順序のヒントであり、コンテナが完全に準備できたかはヘルスチェックで判断するのがベスト。
各サービスは backend ブリッジネットワークに所属し、例えば app コンテナからは db:5432 と名前だけで PostgreSQL に接続できる。

3️⃣ 環境別設定と `.env` 管理

3.1 ファイル構成の例

docker-compose.yml          ← 共通ベース
docker-compose.override.yml ← 開発時に自動適用（デフォルトで読み込まれる）
docker-compose.prod.yml     ← 本番環境専用設定
.env.common                 ← 環境横断的な変数
.env.dev                    ← 開発固有のシークレット
.env.prod                   ← 本番固有のシークレット（CI シークレットで上書き推奨）

docker-compose.yml ← 共通ベース

docker-compose.override.yml ← 開発時に自動適用（デフォルトで読み込まれる）

docker-compose.prod.yml ← 本番環境専用設定

.env.common ← 環境横断的な変数

.env.dev ← 開発固有のシークレット

.env.prod ← 本番固有のシークレット（CI シークレットで上書き推奨）

3.2 ベースファイル

services:
  app:
    build: .
    env_file:
      - .env.common
    volumes:
      - ./:/src

services:

app:

build: .

env_file:

- .env.common

volumes:

- ./:/src

3.3 開発オーバーライド（`docker-compose.override.yml`）

services:
  app:
    environment:
      DEBUG: &quot;1&quot;
    ports:
      - &quot;3000:80&quot;

services:

app:

environment:

DEBUG: "1"

ports:

- "3000:80"

3.4 本番用ファイル（`docker-compose.prod.yml`）

services:
  app:
    env_file:
      - .env.prod
    deploy:
      replicas: 3               # Swarm または Kubernetes 互換ランタイムで有効
      resources:
        limits:
          cpus: &quot;0.5&quot;
          memory: 512M

services:

app:

env_file:

- .env.prod

deploy:

replicas: 3 # Swarm または Kubernetes 互換ランタイムで有効

resources:

limits:

cpus: "0.5"

memory: 512M

注意
deploy: キーは Docker Engine の単体モードでは無視され、Swarm クラスタや Kubernetes‑compatible runtime（例：Docker Desktop の Kubernetes オプション）でのみ適用できる。したがって本番環境でこの設定を利用する場合は、対象ランタイムが Swarm か Kubernetes のいずれかであることを事前に確認しておく。

3.5 `.dockerignore` による機密情報除外

.env*
node_modules/
dist/
.git/

.env*

node_modules/

dist/

.git/

3.6 起動コマンド例

# 開発環境（ベース + override が自動的に適用される）
docker compose up -d

# 本番環境（ベース + prod を明示的に指定）
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --remove-orphans

# 開発環境（ベース + override が自動的に適用される）

docker compose up -d

# 本番環境（ベース + prod を明示的に指定）

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --remove-orphans

4️⃣ ローカル開発での Ingress エミュレーション

Kubernetes の Ingress と同様の URL 構造をローカルでも再現したい場合、Nginx リバースプロキシ を使うと簡単に実装できる。

4.1 Nginx 設定例 (`nginx/conf.d/default.conf`)

server {
    listen 80;

    # /api/app/* → app コンテナへ転送
    location /api/app/ {
        proxy_pass http://app:8080/;
        proxy_set_header Host $host;
    }

    # /api/auth/* → auth コンテナへ転送（例として auth が別サービスの場合）
    location /api/auth/ {
        proxy_pass http://auth:8081/;
        proxy_set_header Host $host;
    }
}

server {

listen 80;

# /api/app/* → app コンテナへ転送

location /api/app/ {

proxy_pass http://app:8080/;

proxy_set_header Host $host;

}

# /api/auth/* → auth コンテナへ転送（例として auth が別サービスの場合）

location /api/auth/ {

proxy_pass http://auth:8081/;

proxy_set_header Host $host;

}

4.2 Compose に Nginx サービス追加

services:
  nginx:
    image: nginx:stable-alpine
    ports:
      - &quot;80:80&quot;
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
    depends_on:
      - app
      - auth   # 必要に応じて追加
    networks:
      - backend

services:

nginx:

image: nginx:stable-alpine

ports:

- "80:80"

volumes:

- ./nginx/conf.d:/etc/nginx/conf.d:ro

depends_on:

- app

- auth # 必要に応じて追加

networks:

- backend

ポイント
- depends_on は 起動順序 のヒントに過ぎない。実際の可用性はコンテナ内部でヘルスチェックを行うか、外部ツール（例：wait-for-it.sh）で待機させることが推奨される。
- proxy_set_header Host $host; により、バックエンド側でオリジナルのホスト名が参照できる。

4.3 よくあるエラーと対処法

エラー	原因	対策
client version too old	Docker CLI と Engine の API バージョン不一致	Docker Desktop／Engine を最新に更新し、`docker version` で両方のバージョンを確認。
ポート競合 (`Bind for 0.0.0.0:80 failed`)	ホスト側に同じポートがすでに使用中	`lsof -i :80` でプロセスを特定し停止、または Compose 側の `ports:` を別ポートに変更。
サービス名が解決できない	コンテナが期待したネットワークに接続していない	`docker compose config` で生成された設定を確認し、全サービスが同一 network に所属しているか検証。

5️⃣ 本番デプロイのベストプラクティス

5.1 `deploy:` セクションの正しい使い方

version: &quot;3.9&quot;

services:
  app:
    image: myorg/app:stable
    deploy:
      replicas: 4                # Swarm / Kubernetes でのみ有効
      resources:
        limits:
          cpus: &quot;0.5&quot;
          memory: 256M
        reservations:
          cpus: &quot;0.2&quot;
          memory: 128M
      restart_policy:
        condition: on-failure
        delay: 10s
        max_attempts: 3
      health_check:
        test: [&quot;CMD&quot;, &quot;curl&quot;, &quot;-f&quot;, &quot;http://localhost/health&quot;]
        interval: 30s
        timeout: 5s
        retries: 3
    environment:
      APP_ENV: production
    networks:
      - backend

networks:
  backend:
    external: true   # 本番では既存のインフラネットワークを流用

version: "3.9"

services:

app:

image: myorg/app:stable

deploy:

replicas: 4 # Swarm / Kubernetes でのみ有効

resources:

limits:

cpus: "0.5"

memory: 256M

reservations:

cpus: "0.2"

memory: 128M

restart_policy:

condition: on-failure

delay: 10s

max_attempts: 3

health_check:

test: ["CMD", "curl", "-f", "http://localhost/health"]

interval: 30s

timeout: 5s

retries: 3

environment:

APP_ENV: production

networks:

- backend

networks:

backend:

external: true # 本番では既存のインフラネットワークを流用

Swarm / Kubernetes 前提：docker compose up 単体で deploy: が機能するわけではない。実際に適用するには docker stack deploy -c docker-compose.yml <stack>（Swarm）や、Docker Desktop の Kubernetes オプションを有効化した上で kubectl apply -f へ変換するツールを使用する必要がある。
ヘルスチェックはコンテナ内部の /health エンドポイントと合わせて実装すると、障害時に自動的に再起動やレプリカ置き換えが行われる。

5.2 CI/CD パイプラインへの組み込み例

GitHub Actions（`.github/workflows/deploy.yml`）

name: Deploy to Production

on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v3

      # Docker Buildx のセットアップ
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2

      # Docker Hub へのログイン（シークレットはリポジトリ設定で管理）
      - name: Log in to Docker Hub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKERHUB_USER }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      # イメージのビルド＆プッシュ
      - name: Build &amp; Push image
        run: |
          IMAGE_TAG=${{ github.sha }}
          docker build -t myorg/app:${IMAGE_TAG} .
          docker push myorg/app:${IMAGE_TAG}}

      # 本番スタックのデプロイ（Swarm 前提）
      - name: Deploy stack
        env:
          COMPOSE_FILE: docker-compose.yml:docker-compose.prod.yml
        run: |
          docker login -u ${{ secrets.DOCKERHUB_USER }} -p ${{ secrets.DOCKERHUB_TOKEN }}
          docker stack deploy -c $COMPOSE_FILE prod-stack

name: Deploy to Production

on:

push:

branches: [ main ]

jobs:

build-and-deploy:

runs-on: ubuntu-latest

permissions:

contents: read

packages: write

steps:

- uses: actions/checkout@v3

# Docker Buildx のセットアップ

- name: Set up Docker Buildx

uses: docker/setup-buildx-action@v2

# Docker Hub へのログイン（シークレットはリポジトリ設定で管理）

- name: Log in to Docker Hub

uses: docker/login-action@v2

with:

username: ${{ secrets.DOCKERHUB_USER }}

password: ${{ secrets.DOCKERHUB_TOKEN }}

# イメージのビルド＆プッシュ

- name: Build & Push image

run: |

IMAGE_TAG=${{ github.sha }}

docker build -t myorg/app:${IMAGE_TAG} .

docker push myorg/app:${IMAGE_TAG}}

# 本番スタックのデプロイ（Swarm 前提）

- name: Deploy stack

env:

COMPOSE_FILE: docker-compose.yml:docker-compose.prod.yml

run: |

docker login -u ${{ secrets.DOCKERHUB_USER }} -p ${{ secrets.DOCKERHUB_TOKEN }}

docker stack deploy -c $COMPOSE_FILE prod-stack

GitLab CI（`.gitlab-ci.yml`）

stages:
  - build
  - deploy

variables:
  IMAGE_REGISTRY: registry.example.com
  IMAGE_NAME: myorg/app

build_image:
  stage: build
  script:
    - docker login -u &quot;$CI_REGISTRY_USER&quot; -p &quot;$CI_REGISTRY_PASSWORD&quot; $CI_REGISTRY
    - docker build -t $IMAGE_REGISTRY/$IMAGE_NAME:$CI_COMMIT_SHA .
    - docker push $IMAGE_REGISTRY/$IMAGE_NAME:$CI_COMMIT_SHA
  only:
    - main

deploy_production:
  stage: deploy
  script:
    - docker login -u &quot;$CI_REGISTRY_USER&quot; -p &quot;$CI_REGISTRY_PASSWORD&quot; $CI_REGISTRY
    - docker stack deploy -c docker-compose.yml -c docker-compose.prod.yml prod-stack
  environment:
    name: production
    url: https://app.example.com
  only:
    - main

stages:

- build

- deploy

variables:

IMAGE_REGISTRY: registry.example.com

IMAGE_NAME: myorg/app

build_image:

stage: build

script:

- docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY

- docker build -t $IMAGE_REGISTRY/$IMAGE_NAME:$CI_COMMIT_SHA .

- docker push $IMAGE_REGISTRY/$IMAGE_NAME:$CI_COMMIT_SHA

only:

- main

deploy_production:

stage: deploy

script:

- docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY

- docker stack deploy -c docker-compose.yml -c docker-compose.prod.yml prod-stack

environment:

name: production

url: https://app.example.com

only:

- main

docker stack deploy を使用することで、deploy: セクションが実際に適用される。Kubernetes 環境の場合は kompose 等で変換し、kubectl apply -f と置き換えることになる。
デプロイ失敗時は GitHub/GitLab のジョブステータス が即座に通知され、ロールバックや手動介入が容易になる。

6️⃣ まとめ ― 実務で役立つポイント

項目	推奨アクション
Compose ファイルのバージョン	`version:` キーは省略可。互換性が必要なら `"3.9"` を使用し、最新仕様は公式リポジトリ（https://github.com/compose-spec/compose-spec）で確認。
ネットワーク設計	カスタムブリッジネットワークを作成し、サービス名で DNS 解決できることを前提に構築。
環境別設定	`docker-compose.yml` + オーバーライド (`override.yml`, `prod.yml`) のマルチファイル方式で管理し、`.env` 系統で機密情報は外部化。
ローカル Ingress エミュ	Nginx リバースプロキシだけで実装できるので、K8s と同一のエンドポイント構造をローカルでも再現可能。
本番デプロイ	`deploy:` は Swarm / Kubernetes 互換ランタイム限定。ヘルスチェック・リソース制限は必ず設定し、CI/CD パイプラインで自動化する。
信頼性の高い情報源	Docker の公式ドキュメントと Compose Specification リポジトリのみを参照し、外部ブログやリンクは避けるか、URL が存在することを必ず確認する。

次に読むべき資料
- Docker Docs – Compose: https://docs.docker.com/compose/
- Compose Specification（GitHub）: https://github.com/compose-spec/compose-spec

このガイドは、Docker Compose の基礎から実務レベルの本番運用まで、一貫した流れで学べるよう構成しています。ぜひ自プロジェクトに取り入れ、コンテナオーケストレーションの効率化と信頼性向上を図ってください。

スポンサードリンク

-Docker

comment コメントをキャンセル

: Docker

DockerとCI/CDの基本と主要ツール別設定ガイド

DockerはCI/CDにおいて環境統一と再現性を保証し、主要ツール別の設定方法やセキュリティ対策まで網羅的に紹介します。

: Docker

Docker client API version mismatch エラーの原因と対策完全ガイド

Docker クライアントとデーモン間で API バージョンが合わないと発生する client API version mismatch エラーの原因と具体的な解消方法を紹介します。

: Docker

Docker API バージョン不一致エラーの対処法と最新版解消手順（2026）

Docker の client and server have different API versions エラーは、バージョン差が原因です。本記事ではバージョン確認から環境変数・daemon.json 設定、最新 Engine への更新手順、GitHub Actions や GitLab CI での固定方法まで実践的に紹介します。

: Docker

Docker Desktop Mac M2 インストール手順 – macOS Ventura での設定方法

M2搭載MacでDocker Desktopを安全にインストールし、すぐにコンテナ開発が始められる手順とポイントを紹介します。

: Docker

Docker コンテナのコスト削減ベストプラクティス：イメージ最適化からスポット活用まで

マルチステージビルドや軽量イメージ、リソース右サイズ化、オートスケール、スポットインスタンス活用など、Dockerコンテナの運用コストを劇的に削減する実践手順を紹介します。

Facebookシェアリンクでメッセージをカスタマイズする方法と注意点

フレッツ光のサービス体系・料金プラン徹底比較と選び方ガイド

Docker Composeで安全に環境別設定を共有する方法 – マイクロサービス実践ガイド

1️⃣ Docker Compose の概要と基本構文

最小構成例

2️⃣ マイクロサービス構成例 ― カスタムネットワークと名前解決

3️⃣ 環境別設定と .env 管理

3.1 ファイル構成の例

3.2 ベースファイル

3.3 開発オーバーライド（docker-compose.override.yml）

3.4 本番用ファイル（docker-compose.prod.yml）

3.5 .dockerignore による機密情報除外

3.6 起動コマンド例

4️⃣ ローカル開発での Ingress エミュレーション

4.1 Nginx 設定例 (nginx/conf.d/default.conf)

4.2 Compose に Nginx サービス追加

4.3 よくあるエラーと対処法

5️⃣ 本番デプロイのベストプラクティス

5.1 deploy: セクションの正しい使い方

5.2 CI/CD パイプラインへの組み込み例

GitHub Actions（.github/workflows/deploy.yml）

GitLab CI（.gitlab-ci.yml）

6️⃣ まとめ ― 実務で役立つポイント

3️⃣ 環境別設定と `.env` 管理

3.3 開発オーバーライド（`docker-compose.override.yml`）

3.4 本番用ファイル（`docker-compose.prod.yml`）

3.5 `.dockerignore` による機密情報除外

4.1 Nginx 設定例 (`nginx/conf.d/default.conf`)

5.1 `deploy:` セクションの正しい使い方

GitHub Actions（`.github/workflows/deploy.yml`）

GitLab CI（`.gitlab-ci.yml`）