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

運営:リナックスマスター.JP(代表 宮崎智広)
HOME > Linux技術 リナックスマスター.JP(Linuxマスター.JP) > Docker > Docker Composeのprofilesで開発・本番・デバッグ用サービスを切り替える方法|--profileオプションとCOMPOSE_PROFILESの実践設計
「docker-compose.yml に開発環境だけで使うサービスを書きたい。でも本番でも同じファイルを使うから、丸ごと削除できない。毎回コメントアウトするのは運用ミスのもとだ。」
そう感じているなら、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で管理する


「このままじゃマズい」と感じていませんか?
参考書を開く気力もない、同年代に取り残される不安——
でも安心してください。プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
姓・名・メールの3つだけ/30秒/解除は3秒 / 詳細はこちら

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:

ルールは 2 つです。

・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

dev プロファイルを持つ 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"

メールモック、DB 管理ツール、Redis 確認ツールを dev プロファイルにまとめる定番構成です。

パターン2:debug(一時的なデバッグ用)

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

分散トレースの Jaeger などを debug プロファイルに入れておき、問題調査のときだけ起動します。

パターン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

Prometheus + Grafana を monitoring プロファイルにまとめておき、ステージング環境でのみ起動する使い方が実務では多いです。

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設計)
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:

compose.override.yml(開発環境で上書きしたい差分設定):

services: app: environment: APP_ENV: development APP_DEBUG: "true" volumes: - .:/app # ソースコードをマウントして即時反映 db: ports: - "5432:5432" # 開発用にDBへ外部から接続できるようにする

本番環境やCI環境では -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]

ルール:profilesなしのサービス(app)は、profilesありのサービスに depends_on してはいけません。profilesありのサービスは同じプロファイルを持つサービスに depends_on してよいです。

トラブルシュートと確認方法

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設計
profiles を使えば「本番はコアサービスだけ、開発は --profile dev を追加」という運用が 1 ファイルで完結します。毎回コメントアウトで対応するミスや、ファイルを 2 つに分けた二重管理から解放されます。
サービスの設定内容(ログレベル・バインドマウント・ポート公開)を環境ごとに変えたい場合は、profiles と組み合わせて compose.override.yml による override 設計を活用してください。-f オプションで本番用ファイルを明示的に指定することで、開発設定の混入も防げます。
現場で通用する安全なLinuxサーバー構築の「型」を体系的に身につけたい方へ、Docker Composeを使った本番・開発環境設計のハンズオンも開催しています。コンテナ設計でつまずきやすいポイントを20年以上の現場経験をもとに解説します。
>> Dockerハンズオン講座の詳細はこちら

無料メルマガで学習を続ける

Linuxの実践スキルをメールで毎週お届け。
登録は30秒、解除もいつでも可。

登録無料・いつでも解除できます

暗記不要・1時間後にはサーバーが動く

3,100名以上が実践した「型」を無料で公開中

プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
その「型」を図解60Pにまとめた入門マニュアルを、完全無料でプレゼントしています。

姓・名・メールの3つだけ/30秒/解除は3秒 / 詳細はこちら

Linux無料マニュアル(図解60P) 名前とメールで30秒登録

運営

リナックスマスター.JP(代表 宮崎智広)

株式会社イーネットマーキュリーが運営するLinux教育サイトです。代表の宮崎智広は現役のLinuxサーバー管理者として20年以上の実務経験を持ち、累計3,100名以上のエンジニアを指導してきました。実践型のLinuxセミナーや無料マニュアルの配布を通じてLinux人材の育成に取り組んでいます。