そう感じているなら、Docker Compose の profiles 機能で解決できます。
profiles はサービスに名前(プロファイル名)を付けておき、その名前を指定したときだけ起動させる仕組みです。compose.yml は 1 つのまま、環境によって起動するサービスを切り替えられます。
この記事では、profiles の書き方から
--profile オプション・COMPOSE_PROFILES 環境変数の使い分け、compose.override.yml による設定差分の管理まで、出力例付きで解説します。動作確認環境:Docker 26.1.4(Docker Compose v2.27)、Ubuntu 24.04 LTS / Rocky Linux 9.4
この記事のポイント
・profilesキーを持つサービスは--profileで指定したときだけ起動する
・profilesなしのサービスは常に起動するコアサービスとして機能する
・COMPOSE_PROFILES環境変数で.envに書けばコマンドを変えずに切り替えられる
・depends_onの参照先がprofiles付きの場合は参照元にも同じprofileを付ける
・「サービスの有無」はprofiles、「設定の差分」はcompose.override.ymlで管理する
でも安心してください。プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
Docker Compose profilesはなぜ必要か
サービスの数が増えると、開発環境でしか使わないサービスが出てきます。・開発中のメール送信をモックする MailHog
・DB の中身を確認する Adminer や pgAdmin
・ローカルでのみ使う Prometheus / Grafana の監視スタック
これらを compose.yml に書くと、
docker compose up で本番環境でも起動してしまいます。かといって本番用・開発用でファイルを分割すると、サービス定義の二重管理になります。Docker Compose の profiles 機能はこの問題を解決します。サービスに名前(プロファイル名)を付けておき、そのプロファイルを指定したときだけ起動させます。compose.yml は 1 つのまま、環境によって起動するサービスを切り替えられます。
profiles は Docker Compose v1.28.0(2021 年 1 月リリース)から利用可能です。現在主流の Compose V2(
docker compose コマンド)では標準でサポートされています。profiles は「サービスを起動するかどうか」を制御する機能です。起動するサービスは同じでも環境ごとに設定内容(ログレベル・バインドマウント・ポート公開など)を変えたい場合は、
compose.override.yml を使った override 設計が適しています。profiles と override の使い分けはこの記事の後半で詳しく解説します。
profilesの基本的な書き方
サービス定義にprofiles: キーを追加します。値は文字列の配列です。
# 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:
・profilesなし:どの起動方法でも常に起動するコアサービス(app, db)
・profilesあり:そのプロファイルが指定されたときだけ起動するオプションサービス(mailhog, pgadmin)
pgadmin のように複数のプロファイル名を並べると、どちらかが指定されれば起動します。配列の代わりに短縮記法 profiles: [dev] も使えます(YAML インラインシーケンス)。動作は同じです。
--profileオプションで選択起動する実践手順
1. プロファイルなしで起動(コアサービスのみ)
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
mailhog と pgadmin は起動していません。profiles が付いているためデフォルトでは除外されます。
2. devプロファイルを指定して起動
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
mailhog と pgadmin が追加起動しています。
3. 複数プロファイルを同時に指定する
docker compose --profile dev --profile monitoring up -d
--profile は複数回指定できます。dev と monitoring 両方のサービスが起動します。
4. 起動中のスタックにプロファイルサービスを追加する
すでにコアサービスが起動している状態から、後でデバッグツールだけ追加起動したい場合:# すでに起動中のスタックに pgadmin だけ追加 docker compose --profile debug up -d pgadmin
COMPOSE_PROFILES環境変数で環境を固定する設計
--profile をコマンドのたびに入力するのは手間です。環境ごとに固定するには COMPOSE_PROFILES 環境変数を使います。
1. シェルの環境変数に設定する
export COMPOSE_PROFILES=dev # 以降は --profile dev を省略できる docker compose up -d
2. .envファイルに書いて自動適用する
compose.yml と同じディレクトリに.env ファイルを置くと、Compose が自動で読み込みます。
# .env(開発環境用) COMPOSE_PROFILES=dev POSTGRES_PASSWORD=localpassword
COMPOSE_PROFILES=dev,monitoring
.env を置かないか、COMPOSE_PROFILES=(空)にしておくと、コアサービスだけが起動します。優先順位:シェルの環境変数 > .env ファイル。どちらも設定されている場合はシェルの値が使われます。
運用のコツ:.env はリポジトリに含めず、開発者ごとにローカルで作成します。代わりに
.env.example(環境変数名と説明だけ記載したサンプル)をリポジトリに含めておくと、チームメンバーが環境構築しやすくなります。
# .env.example(git管理対象) COMPOSE_PROFILES=dev # 開発環境は dev を指定。本番は空欄にする POSTGRES_PASSWORD= # 各自で設定(例: localpassword)
実務でよく使う3つのパターン
Docker Compose profiles を使った本番・開発環境の設計について体系的に学びたい方は、Dockerハンズオン講座(docker.linuxmaster.jp)も参考にしてみてください。パターン1:dev(開発ツール一式)
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"
パターン2:debug(一時的なデバッグ用)
services: jaeger: image: jaegertracing/all-in-one:1.57 profiles: [debug] ports: - "16686:16686" # Jaeger UI - "4317:4317" # OTLP/gRPC
パターン3:monitoring(監視スタック)
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
profilesとoverride設計の使い分け
profiles と似た目的を持つ機能として、compose.override.yml を使った override 設計があります。両者の役割の違いを理解しておくと、適切に使い分けられます。・profiles:サービス自体を起動するかどうかを制御します(サービスの有無を切り替える)
・override:同じサービスの設定を環境ごとに変えます(ログレベル・ポート・バインドマウントの切り替えなど)
「このサービスを本番では起動しない」なら profiles、「このサービスの設定を環境で変えたい」なら override が適切です。
| やりたいこと | 適した機能 |
|---|---|
| 本番ではMailHogを起動しない | profiles |
| 開発時だけソースをバインドマウントする | compose.override.yml(override設計) |
| 開発時はDBのポートをホストに開放したい | compose.override.yml(override設計) |
| Jaegerを調査時だけ起動する | profiles |
| 本番ではappのログレベルをwarnにしたい | compose.override.yml(override設計) |
compose.yml と同じディレクトリに compose.override.yml を置くと、docker compose up が自動でマージして起動します。compose.yml(全環境共通のベース設定):
services: app: build: . environment: APP_ENV: production DB_HOST: db depends_on: - db db: image: postgres:16 environment: POSTGRES_DB: myapp POSTGRES_USER: appuser POSTGRES_PASSWORD: change_me_in_prod volumes: - db_data:/var/lib/postgresql/data volumes: db_data:
services: app: environment: APP_ENV: development APP_DEBUG: "true" volumes: - .:/app # ソースコードをマウントして即時反映 db: ports: - "5432:5432" # 開発用にDBへ外部から接続できるようにする
-f オプションを使って明示的にファイルを指定します。-f を 1 つでも指定すると、compose.override.yml の自動読み込みは無効になります。本番用差分ファイル(compose.prod.yml)を用意しておくと、環境別に切り替えやすくなります。
# 開発環境:compose.override.yml が自動読み込みされる docker compose up -d # 本番環境:-f で明示指定(compose.override.yml は読み込まれない) docker compose -f compose.yml -f compose.prod.yml up -d
docker compose config でマージ後の設定を確認すると、意図しない設定の混入を事前に防げます。profiles と組み合わせる構成も一般的です。profiles でデバッグ用サービスの有無を制御しながら、
compose.override.yml で app サービスのログ設定を切り替えるといった使い方が典型的なパターンです。「サービスの有無」と「設定の差分」という 2 つの軸で分けて考えると、どちらの機能を使うべきかが判断しやすくなります。
depends_onとprofilesを組み合わせる時の注意点
profiles を使う際に最も間違いやすいのがdepends_on との組み合わせです。NG(エラーになる):
services: app: image: myapp:latest # profilesなし depends_on: - redis-debug # profiles付きサービスへの依存 → エラー redis-debug: image: redis:7 profiles: [debug]
docker compose up(プロファイルなし)時に app が起動しようとして redis-debug が見つからずエラーになります。OK(同じprofileを揃える):
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]
トラブルシュートと確認方法
1. どのサービスがどのprofileに属しているか確認する
# コアサービス(profilesなし)だけ表示 docker compose config --services
app db
# dev プロファイル有効時のサービス一覧 docker compose --profile dev config --services
app db mailhog pgadmin
2. 「No such service: xxx」が出た時
profiles が付いたサービスを直接指定しようとして、プロファイルを省略した場合に発生します。# NG: プロファイルなしで profiles 付きサービスを指定 docker compose up mailhog # OK: プロファイルも一緒に指定する docker compose --profile dev up mailhog
3. COMPOSE_PROFILESを設定したのに効かない
.env ファイルのパスが正しいか確認します。compose.yml と同じディレクトリに置く必要があります。シェルの環境変数で上書きされていないかも確認します。
# Compose が認識しているプロファイル設定を確認 docker compose config | grep -A3 "profiles:" # シェルの環境変数を確認 echo $COMPOSE_PROFILES
4. 起動前にマージ設定を確認する
docker compose config はマージ済みの完全な設定を出力します。起動前に確認する習慣をつけると、想定外のサービスが含まれていないかを事前に確かめられます。
# dev プロファイル有効時の完全な設定を表示 docker compose --profile dev config # profiles フィールドだけ抜き出す docker compose config | grep -B2 "profiles:"
本記事のまとめ
Docker Compose profiles を使うと、1 つの compose.yml で環境別のサービス起動を管理できます。| やりたいこと | コマンド・設定 |
|---|---|
| サービスにプロファイルを設定する | profiles: [dev](compose.yml内) |
| プロファイルを指定して起動する | docker compose --profile dev up -d |
| 複数プロファイルを同時に有効化する | docker compose --profile dev --profile debug up -d |
| 環境変数でプロファイルを固定する | COMPOSE_PROFILES=dev(.envに記載) |
| 有効なサービス一覧を確認する | docker compose --profile dev config --services |
| 本番では開発ツールを起動しない | .envを置かないか、COMPOSE_PROFILES=(空)にする |
| 開発用の設定差分を自動で読み込む | compose.override.ymlをcompose.ymlと同じ場所に置く |
| 本番で明示的にファイルを指定する | docker compose -f compose.yml -f compose.prod.yml up -d |
| サービスの設定を環境ごとに変える | compose.override.yml を使ったoverride設計 |
--profile dev を追加」という運用が 1 ファイルで完結します。毎回コメントアウトで対応するミスや、ファイルを 2 つに分けた二重管理から解放されます。サービスの設定内容(ログレベル・バインドマウント・ポート公開)を環境ごとに変えたい場合は、profiles と組み合わせて
compose.override.yml による override 設計を活用してください。-f オプションで本番用ファイルを明示的に指定することで、開発設定の混入も防げます。
>> Dockerハンズオン講座の詳細はこちら
3,100名以上が実践した「型」を無料で公開中
プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
その「型」を図解60Pにまとめた入門マニュアルを、完全無料でプレゼントしています。
姓・名・メールの3つだけ/30秒/解除は3秒 / 詳細はこちら
- 次のページへ:DockerfileのFROM設計|debian・alpine・distrolessのベースイメージを比較して最適解を選ぶ方法
- 前のページへ:DockerfileのCOPYで何が起きているか|ビルドコンテキストとレイヤー設計を理解する
- この記事の属するカテゴリ:Dockerへ戻る

無料メルマガで学習を続ける
Linuxの実践スキルをメールで毎週お届け。
登録は30秒、解除もいつでも可。
登録無料・いつでも解除できます