Compose Dev Services
Compose Dev Services は、Compose 仕様を使用してカスタム dev services を定義する方法を提供します。
Quarkus Dev Services は、開発モードおよびテストモードで未構成のサービスを自動的にプロビジョニングします。サービスへの接続を提供するほとんどのエクステンションは、舞台裏で Testcontainers を使用して dev services の実装も提供します。各 dev service には、使用するコンテナーイメージなどのデフォルト設定がありますが、カスタマイズの点で制限があります。
このレベルの自動化はほとんどのユースケースに最適ですが、プロビジョニングされたサービスに対してより多くの制御と調整が必要な場合があります。
Compose Dev Services は、Compose Specification を使用してカスタムの dev services を定義できるようにすることで、Dev Services の概念を拡張します。Compose Specification は、クラウドとプラットフォームに依存しないコンテナーベースのアプリケーションを定義するための、開発者向けの標準です。
Compose は、開発およびテスト目的でマルチコンテナーアプリケーションを定義および管理するために広く使用されているツールです。
通常 compose.yml という名前の YAML 記述ファイルは、アプリケーションに必要なサービス、ネットワーク、およびボリュームを定義します。
Docker Compose はリファレンス実装であり、 Podman Desktop も Compose specification のすぐに使えるサポートを提供します。
Quarkus は、プロジェクト内の compose-devservices.yml ファイル (または 特定の Compose ファイルの使用) を検出し、アプリケーションが開発モードまたはテストモードで実行されるときに定義されたサービスを起動します。dev services を提供するエクステンションは、これらのカスタムサービスを発見し、デフォルトのサービスを作成する代わりにそれらを使用します。開発モードまたはテストが停止すると、サービスは自動的に停止してクリーンアップされます。
この統合により、シームレスな開発エクスペリエンスが提供され、サービスの構成を完全に制御できます。
前提条件
Compose Dev Services を使用するには、次のものが必要です。
-
$PATHに存在するdockerまたはpodmanCLI -
docker-composeまたはpodman-composeのような Compose ツール (docker composeおよびpodman composeコマンドは内部でこれらのバイナリを呼び出すことに注意してください):-
Docker の場合: Docker Compose のインストール
-
Podman の場合: Compose の設定
-
|
Compose Dev Services は Compose V2 のみと互換性があります。 |
Compose Dev Services の使用
簡単なシナリオからより複雑なシナリオまで、例を挙げて Compose Dev Services の使用方法を見ていきましょう。
基本的な例: PostgreSQL データベース
quarkus-jdbc-postgresql エクステンションを使用するようにすでに設定されている Quarkus プロジェクトで、プロジェクトのルートに compose-devservices.yml ファイルを作成し、Compose を使用してカスタムサービスを定義できます。
services:
db:
image: docker.io/library/postgres:18
healthcheck:
test: pg_isready -U myuser -d mydb
interval: 5s
timeout: 3s
retries: 3
ports:
- '5432'
environment:
POSTGRES_USER: myuser
POSTGRES_PASSWORD: mypassword
POSTGRES_DB: mydb開発モードでアプリケーションを実行したりテストを実行したりすると、Compose Dev Services は、quarkus-jdbc-postgresql エクステンションによって提供されるデフォルトの dev service を使用する代わりに、compose-devservices.yml ファイルで定義された PostgreSQL サービスを自動的に起動します。
上記の構成に従って、PostgreSQL コンテナーポート 5432 はランダムなホストポートに公開され、アプリケーションデータソースは ユーザー、パスワード、データベース名 などの接続情報を抽出することによって構成されます。
複数サービスの例: カスタムネットワークと依存関係
より複雑なシナリオでは、カスタムネットワークとサービスの依存関係を定義できます。
services:
db:
image: docker.io/library/postgres:18
ports:
- '5432'
environment:
POSTGRES_USER: myuser
POSTGRES_PASSWORD: mypassword
POSTGRES_DB: mydb
networks:
- backend
volumes:
- postgres-data:/var/lib/postgresql/data
cache:
image: docker.io/library/redis:7
command: redis-server --save 60 1 --loglevel warning
ports:
- '6379'
networks:
- backend
depends_on:
- db
message-broker:
image: docker.io/library/rabbitmq:3.12-management
ports:
- '5672'
- '15672'
networks:
- backend
- frontend
environment:
RABBITMQ_DEFAULT_USER: guest
RABBITMQ_DEFAULT_PASS: guest
api-gateway:
image: nginx:latest
ports:
- '8080:80'
networks:
- frontend
depends_on:
- message-broker
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
networks:
backend:
frontend:
volumes:
postgres-data:必要に応じて compose-devservices.yml ファイルをカスタマイズして、起動順序を制御する依存関係を持つ複数のサービス、サービス通信を分離するカスタムネットワーク、およびデータ永続化と構成のためのボリュームを使用できることに注意してください。
サービスディスカバリー
Compose Dev Services によって開始されたサービスは、dev services を提供するエクステンションによって自動的に検出されます。各エクステンションは必要なサービスを検出し、それに応じてアプリケーションを構成します。
エクステンションは、サービスを検出するためにコンテナーイメージ名と公開ポートに依存します。たとえば、PostgreSQL Dev Service は、イメージ名に postgres を 含む サービスと、公開されたコンテナーポート 5432 を探します。
一致が見つかると、エクステンションは次のように動作します。
-
コンテナーから接続情報 (接続 URL、クレデンシャル、データベース名など) を抽出します。
-
検出されたサービスを使用するようにアプリケーションを構成します
-
独自のデフォルト Dev Service コンテナーの作成をスキップします
サポートされているエクステンションと検出基準
以下は、dev services をサポートするプラットフォームエクステンションのリストです。
| エクステンション | イメージ名 | 公開ポート |
|---|---|---|
AMQP |
amqp, activemq-artemis, amq-broker, rabbitmq |
5672 |
Apicurio Registry |
apicurio |
8080 |
DB2 |
db2 |
50000 |
MySQL |
mysql |
3306 |
PostgreSQL |
PostgreSQL |
5432 |
MariaDB |
mariadb |
3306 |
Microsoft SQL Server |
mssql |
1433 |
Oracle Database |
oracle |
1521 |
Kafka |
kafka, strimzi, redpanda |
9092 |
Keycloak |
keycloak |
8080 |
Kubernetes |
kube-apiserver, k3s, kindest/node |
6443 |
LRA |
LRAコーディネーター |
8080 |
MongoDB |
mongo |
27017 |
MQTT |
hivemq, eclipse-mosquitto |
1883 |
RabbitMQ |
rabbitmq |
5672 |
Pulsar |
pulsar |
6650 |
Redis |
redis |
6379 |
Infinispan |
infinispan, データグリッド |
11222 |
Elasticsearch |
elasticsearch, opensearch |
9200 |
Observability |
lgtm |
16686, 9411, 9090, 3000 |
サービスディスカバリー用のカスタムイメージの設定
サービスディスカバリーに使用されるイメージ名を、application.properties ファイルで適切なプロパティーを設定することでカスタマイズできます。例えば、カスタム Kafka イメージを使用するには:
quarkus.kafka.devservices.image-name=my-custom-kafka:latestDev Services を提供する各エクステンションには、イメージ名をカスタマイズするための独自の設定プロパティーがあります。詳細は、特定のエクステンションのドキュメントを参照してください。
特定の Compose ファイルの使用
デフォルトでは、Compose Dev Services はプロジェクトのルートにある compose-devservices.[yml|yaml] または docker-compose-devservices.[yml|yaml] という名前のファイルを検索します。
application.properties ファイルで quarkus.compose.devservices.files プロパティーを設定することで、使用するカスタムファイルを指定できます:
# Use a specific compose file for all modes
quarkus.compose.devservices.files=src/main/docker/compose.yml
# Use different compose files for different config profiles
%dev.quarkus.compose.devservices.files=src/main/docker/dev-compose.yml
%test.quarkus.compose.devservices.files=src/test/resources/test-compose.ymlこれにより、Quarkus の設定プロファイルに応じて異なる dev service 環境を使用できます。複数のファイルをカンマで区切って指定することも可能です:
quarkus.compose.devservices.files=src/main/docker/base-compose.yml,src/main/docker/extra-services.ymlCompose プロファイルの使用
プロファイルを使用すると、Compose ファイルはアクティブなプロファイルのセットを定義でき、それによって起動されたサービスはさまざまな用途や環境に合わせて調整されます。アクティブ化するプロファイルは、 application.properties ファイルで quarkus.compose.devservices.profiles プロパティーを設定して指定できます:
services:
db:
image: docker.io/library/postgres:18
profiles:
- dev
- local
ports:
- '5432'
environment:
POSTGRES_USER: myuser
POSTGRES_PASSWORD: mypassword
POSTGRES_DB: mydb%test.quarkus.compose.devservices.profiles=dev,localサービスの無視
Compose Dev Services では、Compose ファイルのサービスに io.quarkus.devservices.compose.ignore ラベルを追加することで、特定のサービスを検出しないように設定できます:
services:
db:
image: docker.io/library/postgres:18
labels:
io.quarkus.devservices.compose.ignore: true
ports:
- '5432'
environment:
POSTGRES_USER: myuser
POSTGRES_PASSWORD: mypassword
POSTGRES_DB: mydbサービスにこのラベルが true に設定されている場合、そのサービスはサービスディスカバリーから除外され、エクステンションは Dev Services にそのサービスを使用しません。
サービスの準備完了
Compose Dev Services は、アプリケーションがサービスを使用しようとする前に、サービスが準備完了であることを確認するためのいくつかの方法を提供します。
ヘルスチェック
Compose Dev Services は、Compose ファイルで定義されたヘルスチェックを尊重します。アプリケーションがサービスを使用しようとする前に、サービスが準備完了であることを確認するために、サービスのヘルスチェックを設定することをお勧めします:
services:
db:
image: docker.io/library/postgres:18
healthcheck:
test: pg_isready -U myuser -d mydb
interval: 5s
timeout: 3s
retries: 3
ports:
- '5432'
environment:
POSTGRES_USER: myuser
POSTGRES_PASSWORD: mypassword
POSTGRES_DB: mydbログを待機
Compose Dev Services では、特定のログメッセージがコンテナーログに表示されるまで待機してから、サービスが準備完了と見なすように設定できます。これは、ヘルスチェックを提供しないが、準備完了時にメッセージをログに出力するサービスに役立ちます。
特定のログメッセージを待機するには、 io.quarkus.devservices.compose.wait_for.logs というプレフィックスを持つラベルをサービスに追加します:
services:
app:
image: my-application:latest
ports:
- '8080'
labels:
io.quarkus.devservices.compose.wait_for.logs: .*Server is now running.*数値サフィックスの値を設定することで、ログメッセージが何回表示されるべきかを指定することもできます: io.quarkus.devservices.compose.wait_for.logs.3: .*Worker started.*
ポートを待機
デフォルトでは、Compose Dev Services は、サービスが準備完了と見なす前に、公開されているすべてのポートが利用可能になるまで待機します。この動作はラベルを使用してカスタマイズできます:
services:
app:
image: my-application:latest
ports:
- '8080'
labels:
# Change to `true` to disable waiting for ports
io.quarkus.devservices.compose.wait_for.ports.disable: false
# Or set a custom timeout for port waiting
io.quarkus.devservices.compose.wait_for.ports.timeout: "30s"グローバルタイムアウト
Dev Services の起動におけるグローバルタイムアウトは、 quarkus.devservices.timeout プロパティーを使用して設定できます:
quarkus.devservices.timeout=120sこのプロパティーは、すべての Dev Services が起動するまでに待機する最大時間を設定します。デフォルトは 60 秒です。
サービスの順序付け
Compose Dev Services は、Compose ファイルで定義されている順序でサービスを起動します。特定の順序でサービスを起動する必要がある場合は、 depends_on 属性を使用できます:
services:
db:
image: docker.io/library/postgres:18
ports:
- '5432'
environment:
POSTGRES_USER: myuser
POSTGRES_PASSWORD: mypassword
POSTGRES_DB: mydb
app:
image: my-application:latest
ports:
- '8080'
depends_on:
- dbサービス設定をアプリケーションに公開する
Compose Dev Services は、検出されたサービスの構成をアプリケーションに自動的に公開します。たとえば、次の compose サービス記述でデータベースサービスが検出された場合:
services:
db:
image: docker.io/library/mysql:9.5
ports:
- '9906:3306'
labels:
io.quarkus.devservices.compose.jdbc.parameters: characterEncoding=UTF-8&useUnicode=true
environment:
MYSQL_USER: myuser
MYSQL_PASSWORD: mypassword
MYSQL_DATABASE: mydb以下のアプリケーションプロパティーが自動的に設定されます:
quarkus.datasource.username=myuser
quarkus.datasource.password=mypassword
quarkus.datasource.jdbc.url=jdbc:mysql://localhost:9906/mydb?characterEncoding=UTF-8&useUnicode=true実際の値はサービスラベルと環境変数から抽出されます。ホストは Docker ホストの IP アドレスに設定され、ポートはホスト上のマッピングされたポートに設定されます。
|
データベースサービスの場合、 |
サービスラベルを使用したカスタム設定マッピング
サービスラベルを使用して、環境変数と公開ポートをアプリケーション設定プロパティーにマッピングする方法をカスタマイズできます。
環境変数のマッピング
環境変数を特定のアプリケーション設定プロパティーにマッピングするには、 io.quarkus.devservices.compose.config_map.env.<env-var-name> ラベルを使用します。
MQTT ブローカーの例を見てみましょう:
services:
mqtt:
image: eclipse-mosquitto:2.0.21
ports:
- '1883'
environment:
MQTT_USER: user
MQTT_PASSWORD: pass
labels:
io.quarkus.devservices.compose.config_map.env.MQTT_USER: mp.messaging.connector.smallrye-mqtt.username
io.quarkus.devservices.compose.config_map.env.MQTT_PASSWORD: mp.messaging.connector.smallrye-mqtt.password
volumes:
- ./conf:/mosquitto/configmosquitto.conf ファイルを含む ./conf の場合:
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
listener 1883
allow_anonymous false
password_file /mosquitto/config/password.txtユーザーと暗号化されたパスワードを含む password.txt ファイルの場合:
user:$7$101$EyGShytu3v+...==この例では:
-
値
userを持つMQTT_USER環境変数は、mp.messaging.connector.smallrye-mqtt.usernameプロパティーにマッピングされます -
値
passを持つMQTT_PASSWORD環境変数は、mp.messaging.connector.smallrye-mqtt.passwordプロパティーにマッピングされます
|
|
公開ポートのマッピング
公開ポートを特定のアプリケーション設定プロパティーにマッピングするには、 io.quarkus.devservices.compose.config_map.port.<container-port> ラベルを使用します:
services:
my-service:
image: my-service-image
ports:
- '7432:5432'
- '9080:8080'
labels:
# Map port 5432 to quarkus.datasource.jdbc.port
io.quarkus.devservices.compose.config_map.port.5432: quarkus.datasource.jdbc.port
# Map port 8080 to quarkus.http.port
io.quarkus.devservices.compose.config_map.port.8080: quarkus.http.port上記の例では: - ポート 7432 は quarkus.datasource.jdbc.port プロパティーにマッピングされます - ポート 9080 は quarkus.http.port プロパティーにマッピングされます
マッピングされたプロパティーには、コンテナーポートにマッピングされたホストポートが含まれます。動的ポートマッピング (例: - '7432:5432' ではなく - '5432') を使用している場合、これはコンテナーポートとは異なる場合があります。
実行中のコンテナーへのポートマッピングの公開
場合によっては、コンテナーは実行時にマッピングされているホストポートを知る必要があります。たとえば、Kafka ブローカーは外部からアクセス可能なアドレスをクライアントにアドバタイズする必要があります。
io.quarkus.devservices.compose.exposed_ports ラベルを使用して、ポートマッピングが書き込まれるコンテナー内のファイルパスを指定できます:
services:
kafka:
image: apache/kafka-native:3.9.0
ports:
- '9092'
labels:
io.quarkus.devservices.compose.exposed_ports: /etc/kafka/docker/portsコンテナーが起動すると、Quarkus は指定されたパスに環境変数形式のポートマッピングを含むファイルをコピーします:
PORT_9092=54321
PORT_8080=12345
# ... other ports as needed各行は PORT_<containerPort>=<hostPort> の形式に従います。ここで containerPort はコンテナーによって公開されるポートであり、 hostPort はホストに動的に割り当てられるポートです。コンテナーコマンドはファイルが存在するまで待機し、このファイルをソースとしてこれらのマッピングに環境変数としてアクセスできます:
#!/bin/bash
# Wait for the ports file to be created
while [ ! -f /etc/kafka/docker/ports ]; do
sleep 0.1;
done;
# Source the file to load PORT_* variables
source /etc/kafka/docker/ports;
# Use the port mappings
export KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://localhost:$PORT_9092;
# Run the Kafka broker executable
/etc/kafka/docker/runCompose でのサービスライフサイクルの制御
Compose Dev Services は、サービスの起動、停止、およびアプリケーションインスタンス間での共有方法を制御するためのいくつかの設定オプションを提供します。
アプリケーションが開発モードまたはテストモードで起動すると、Compose Dev Services は設定に基づいてサービスを起動するか、すでに実行中のサービスを検出するかを決定します。アプリケーションが停止すると、Compose Dev Services は起動したサービスを停止します。
Compose プロジェクト名
Compose は、異なる Compose プロジェクトを名前空間化して分離するために、サービス、ネットワーク、ボリュームなどのリソースを識別するためにプロジェクト名を使用します。これにより、アプリケーションが停止したときに、既存のリソースの検出とリソースのクリーンアップが可能になります。
Compose Dev Services は、次のようにプロジェクト名を決定します。
-
quarkus.compose.devservices.project-nameプロパティーが設定されている場合、それがプロジェクト名として使用されます。 -
Compose ファイルでトップレベルの
name属性が指定されている場合、それがプロジェクト名として使用されます。 -
それ以外の場合、デフォルト名
quarkus-devservices-<application-name>が選択されます。
既に起動している Compose Services の検出
プロジェクト名が決定されると、Compose Dev Services はまず、そのプロジェクト名で既存のサービスを検出を試みます。
既に起動している Compose プロジェクトは、同じプロジェクト名でローカルで実行されている別の Quarkus アプリケーションによって起動されたか、または docker compose up もしくは podman compose up コマンドを使用して手動で起動された可能性があります。
サービスがどのように起動されたかに関わらず、Compose Dev Services は dev services と挿入された設定プロパティーを設定しますが、アプリケーションが停止してもサービスは停止しません。
|
プロジェクト内に Compose ファイルが見つからず、 |
テストに使用される Compose Dev Services
Quarkus テストの場合、テスト実行と開発モードサービスの実行との間の分離を確実にするため、デフォルトでは quarkus-devservices-<application-name>-<random-suffix> 形式の生成されたプロジェクト名が使用されます。Compose ファイルでトップレベルの name 属性が指定されている場合、<compose-name>-<random-suffix> 形式のプロジェクト名が使用されます。
この方法により、Quarkus テストは Compose ファイルで定義されたサービスの個別のコピーを開始します。たとえば、開発モードで連続テストを実行する場合、テストは独自の分離されたサービスセットを持つことになります。
この動作は、quarkus.compose.devservices.reuse-project-for-tests=true プロパティーを設定することで変更できます。これにより、テストは開発モードで個別に起動されたサービスを再利用できます。
起動/停止コントロールの使用
デフォルトのライフサイクルでは、Compose Dev Services はアプリケーションの起動と停止時にサービスを自動的に起動および停止します。より詳細な制御には、start-services と stop-services の設定プロパティーを使用できます。
quarkus.compose.devservices.start-services=false が設定されている場合、Compose Dev Services は、決定されたプロジェクト名で既存のサービスを検出を試みるだけで、Compose ファイルが存在しても新しいサービスは起動しません。
quarkus.compose.devservices.stop-services=false が設定されている場合、アプリケーションが停止した後もサービスは実行を継続します。これにより、サービスを他のアプリケーションや同じアプリケーションの後続の実行で再利用できます。
quarkus.compose.devservices.stop-timeout プロパティーでサービスの停止タイムアウトを設定することもできます。タイムアウト後、Compose Dev Services はサービスを強制的に停止します。高速なクリーンアップのために、デフォルトのタイムアウトは意図的に短く (1 秒) 設定されていますが、必要に応じて長くすることができます。
# application.properties
quarkus.compose.devservices.stop-timeout=10s既存の Dev Services との関係
Compose Dev Services は、Quarkus エクステンションによって提供される既存の Dev Services の実装と連携して動作します。サービス検出プロセスは次の優先順位に従います。
-
Dev Service の実装は、まず共有サービスラベルを介してサービス (例: 他のアプリケーションによって開始されたサービス) の特定を試みます。
-
共有サービスが見つからない場合、Compose Dev Services によって開始されたサービスの検出にフォールバックします。
-
Compose サービスが見つからない場合、デフォルトの Dev Services の実装が使用されます (通常は Testcontainers ベースのサービスが起動されます)。
Compose Dev Service がプロジェクトを作成または検出すると、通常の dev service の実装は Compose プロジェクトのデフォルトネットワーク内にコンテナーを作成します。これにより、すべてのサービスが同じネットワーク内でサービス名をホスト名として使用して相互に通信できるようになります。
設定リファレンス
ビルド時に固定される設定プロパティ - その他の設定プロパティは実行時にオーバーライド可能です。
Configuration property |
型 |
デフォルト |
|---|---|---|
Compose dev service enabled or disabled Environment variable: Show more |
boolean |
|
List of file paths relative to the project root for Compose dev service configuration, if not provided will look for compose files in the project root Environment variable: Show more |
文字列のリスト |
|
Name of the compose project, used to discover running containers, if not provided a project name will be generated Environment variable: Show more |
string |
|
Compose profiles to activate Environment variable: Show more |
文字列のリスト |
|
List of additional options to pass to compose command Environment variable: Show more |
文字列のリスト |
|
Whether to run compose up and start containers at startup, when disabled, services are discovered by project name Environment variable: Show more |
boolean |
|
Whether to run compose down and stop containers at shutdown Environment variable: Show more |
boolean |
|
Whether to use test containers Ryuk resource reaper to clean up containers Environment variable: Show more |
boolean |
|
Whether to remove volumes on compose down Environment variable: Show more |
boolean |
|
Which images to remove on compose down Locally built images, without custom tags are removed by default. Environment variable: Show more |
|
|
Env variables to pass to all Compose instances Environment variable: Show more |
Map<String,String> |
|
Scale configuration for services: Configure the number of instances for specific services Environment variable: Show more |
Map<String,Integer> |
|
Whether to tail container logs to the console Environment variable: Show more |
boolean |
|
Whether to build images before starting containers. When not provided, Compose images are built per-service Environment variable: Show more |
boolean |
|
Whether to reuse the project for tests, when disabled, a new project is created for each test run Environment variable: Show more |
boolean |
|
Timeout for stopping services, after the timeout the services are forcefully stopped, Environment variable: Show more |
|
|
期間フォーマットについて
期間の値を書くには、標準の 数字で始まる簡略化した書式を使うこともできます:
その他の場合は、簡略化されたフォーマットが解析のために
|
