Docker Composeのprofilesで開発・本番・デバッグ用サービスを切り替える方法｜--profileオプションとCOMPOSE_PROFILESの実践設計

この記事のポイント

・profilesキーを持つサービスは--profileで指定した時だけ起動する
・profilesなしのサービスは常に起動するコアサービスとして機能する
・COMPOSE_PROFILES環境変数で.envに書けばコマンドを変えずに切り替えられる
・depends_onの参照先がprofiles付きの場合は参照元にも同じprofileを付ける

# compose.yml
services:
  app:
    image: myapp:latest
    ports:
      - "8080:8080"
    depends_on:
      - db
    # profilesなし → 常に起動するコアサービス

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - db_data:/var/lib/postgresql/data
    # profilesなし → 常に起動するコアサービス

  mailhog:
    image: mailhog/mailhog:v1.0.1
    profiles:
      - dev        # devプロファイル時のみ起動
    ports:
      - "8025:8025"

  pgadmin:
    image: dpage/pgadmin4:8
    profiles:
      - dev        # devプロファイル時のみ起動
      - debug      # debugプロファイル時にも起動
    environment:
      PGADMIN_DEFAULT_EMAIL: admin@example.com
      PGADMIN_DEFAULT_PASSWORD: admin
    ports:
      - "5050:80"

volumes:
  db_data:

docker compose up -d

[+] Running 3/3
 ✔ Network myproject_default  Created                          0.1s
 ✔ Container myproject-db-1   Started                          0.4s
 ✔ Container myproject-app-1  Started                          0.7s

docker compose --profile dev up -d

[+] Running 5/5
 ✔ Network myproject_default      Created                          0.1s
 ✔ Container myproject-db-1       Started                          0.4s
 ✔ Container myproject-app-1      Started                          0.7s
 ✔ Container myproject-mailhog-1  Started                          0.8s
 ✔ Container myproject-pgadmin-1  Started                          0.9s

docker compose --profile dev --profile monitoring up -d

# すでに起動中のスタックに pgadmin だけ追加
docker compose --profile debug up -d pgadmin

export COMPOSE_PROFILES=dev

# 以降は --profile dev を省略できる
docker compose up -d

# .env（開発環境用）
COMPOSE_PROFILES=dev
POSTGRES_PASSWORD=localpassword

COMPOSE_PROFILES=dev,monitoring

services:
  mailhog:
    image: mailhog/mailhog:v1.0.1
    profiles: [dev]
    ports:
      - "8025:8025"   # Web UI（ http://localhost:8025 ）

  adminer:
    image: adminer:4.8
    profiles: [dev]
    ports:
      - "8080:8080"
    environment:
      ADMINER_DEFAULT_SERVER: db

  redis-commander:
    image: ghcr.io/joeferner/redis-commander:latest
    profiles: [dev]
    ports:
      - "8081:8081"
    environment:
      REDIS_HOSTS: "local:redis:6379"

services:
  jaeger:
    image: jaegertracing/all-in-one:1.57
    profiles: [debug]
    ports:
      - "16686:16686"  # Jaeger UI
      - "4317:4317"    # OTLP/gRPC

services:
  prometheus:
    image: prom/prometheus:v2.52.0
    profiles: [monitoring]
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana:10.4.2
    profiles: [monitoring]
    ports:
      - "3000:3000"
    depends_on:
      - prometheus

services:
  app:
    image: myapp:latest
    # profilesなし
    depends_on:
      - redis-debug   # profiles付きサービスへの依存 → エラー

  redis-debug:
    image: redis:7
    profiles: [debug]

services:
  app:
    image: myapp:latest
    # profilesなし → コアサービス。profilesなしのサービスにだけ depends_on する

  app-debug:
    image: myapp:debug
    profiles: [debug]
    depends_on:
      - redis-debug   # 同じ debug プロファイルを持つサービスへの依存はOK

  redis-debug:
    image: redis:7
    profiles: [debug]

# コアサービス（profilesなし）だけ表示
docker compose config --services

app
db

# dev プロファイル有効時のサービス一覧
docker compose --profile dev config --services

app
db
mailhog
pgadmin

# NG: プロファイルなしで profiles 付きサービスを指定
docker compose up mailhog

# OK: プロファイルも一緒に指定する
docker compose --profile dev up mailhog

# Compose が認識しているプロファイル設定を確認
docker compose config | grep -A3 "profiles:"

# シェルの環境変数を確認
echo $COMPOSE_PROFILES