The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

Quarkusエクステンションレジストリ

Quarkus CLIMavenGradleプラグインなどのQuarkus開発ツール、または code.quarkus.ioは、Quarkusエコシステムを一覧表示し、特定の条件に一致するエクステンションを検索することができます。これには、 Quarkusプラットフォーム のエクステンションや、コミュニティによって貢献されたその他のさまざまなエクステンションが含まれ、その多くは Quarkiverse Hubでホストされています。

利用可能なすべてのQuarkusエクステンションに関する情報は、 Quarkusエクステンションレジストリ によって開発ツールに提供されます。

Quarkusのエクステンションレジストリは、以下の情報を提供するデータベースです。

  • 利用可能なQuarkusプラットフォームのうち、どのプラットフォームが新規プロジェクトやアップデートに推奨されているか

  • 利用可能なプラットフォーム以外のエクステンションについて、それらがどのQuarkusバージョンと互換性があるか

registry.quarkus.io

registry.quarkus.ioにあるレジストリは、デフォルトのQuarkusコミュニティエクステンションレジストリです。このレジストリは、 Quarkusコミュニティプラットフォームのリリースごとに更新され、 Quarkiverse Hubにホストされているエクステンションも含まれます。

Mavenリポジトリ

registry.quarkus.ioにあるレジストリは、Maven スナップショット リポジトリであり、プラットフォームとエクステンションカタログをMaven JSONアーティファクトとして開発ツールに提供します。エクステンションカタログはダウンロードされると、ユーザーのローカルMavenリポジトリにキャッシュされ、インターネットネットワーク(またはレジストリ自体)が利用できない場合でも、開発ツールで利用できます。

ローカルにキャッシュされたエクステンションカタログアーティファクトは、定期的に更新がチェックされ、それらのカタログの新しいバージョンがレジストリで利用可能な場合は更新されます。更新をチェックするデフォルトの間隔は 毎日 で、これはSNAPSHOTアーティファクトのデフォルトのMavenリポジトリ updatePolicy に一致します。

Mavenリポジトリの設定

以下のリポジトリの設定は、説明のためだけに示されており、ユーザーの settings.xml やアプリケーションの pom.xml に追加する必要はあり ません。Quarkusの開発ツールには、このリポジトリがあらかじめ設定されています。

registry.quarkus.ioMavenリポジトリ設定は以下の通りです。

<repository>
  <id>registry.quarkus.io</id>
  <name>Quarkus community extension registry</name>
  <url>https://registry.quarkus.io/maven</url>
  <snapshots>
    <enabled>true</enabled>
    <updatePolicy>daily</updatePolicy>
    <checksumPolicy>warn</checksumPolicy>
  </snapshots>
</repository>

Quarkus開発ツールが初期化されると、このリポジトリ設定が自動的にMavenリゾルバに追加され、 registry.quarkus.io からのプラットフォームおよびエクステンションカタログの解決に使用されます。

Mavenリポジトリのミラーとプロキシ

Quarkus dev toolsのMavenリゾルバが初期化されると、ユーザー settings.xml の関連するMavenミラーとプロキシは、あたかも registry.quarkus.io Mavenリポジトリがユーザー settings.xml で構成されているかのように、自動的に registry.quarkus.io Mavenリポジトリ設定に適用されます。

つまり、例えば registry.quarkus.io Maven リポジトリに一致する Maven リポジトリミラーを適用した場合、 registry.quarkus.ioMaven リポジトリを対応する Maven サーバーインスタンス (Nexus など) のミラーリポジトリグループに追加する必要があります。

デフォルトのレジストリMavenリポジトリ設定の上書き

The default registry Maven repository configuration can actually be overridden in the user settings.xml by simply adding the desired <repository> configuration with the registry.quarkus.io as its <id> value. If such a repository configuration is found in the user settings.xml, the dev tools will use it in place of the default registry.quarkus.io Maven repository configuration shown above.

Quarkus Extensionのレジストリクライアント設定

通常、Quarkusのコミュニティユーザーは、自分の環境でレジストリ関連の設定を行う必要はありません。 registry.quarkus.io にホストされているレジストリは、デフォルトですべてのQuarkus開発ツールで有効になっています。しかし、カスタムのレジストリクライアント設定が役立つ場面がいくつかあるかもしれません。例えば、ローカルレジストリキャッシュのアップデートポリシーの変更や、追加の(デフォルトではない)Quarkusエクステンションレジストリの設定などです。

レジストリクライアント設定の位置

Quarkus開発ツールを起動すると、以下の手順でレジストリクライアント設定ファイルの検索が行われます。

  1. quarkus.tools.config システムプロパティがチェックされ、存在すればその値がレジストリクライアント設定ファイルへのパスとして使用されます。

  2. カレントディレクトリに .quarkus/config.yaml ファイルが存在するかどうかを確認し、ファイルが存在すれば、それを使用してレジストリクライアントが設定されます。

  3. ユーザーのホームディレクトリに ~/.quarkus/config.yaml ファイルが存在するかどうかを確認し、ファイルが存在する場合は、それを使用してレジストリクライアントを設定します。

  4. 上記のいずれの手順でも設定ファイルが見つからない場合は、デフォルトの registry.quarkus.io 設定が使用されます。

複数のレジストリーを設定

The registry.quarkus.io is the default Quarkus community extension registry, but it is not meant to be always the only registry. Other organizations may find it useful to create their own Quarkus extension registries to provide their own Quarkus platforms and/or individual (non-platform) Quarkus extensions. Users wishing to enable custom Quarkus extension registries in their environment would need to add them to the registry client configuration file.

レジストリクライアント設定ファイルは、レジストリのリストを含むシンプルなYAMLファイルです。例えば以下のようになります。

registries:
- registry.acme.org
- registry.quarkus.io

上記の設定では、 registry.acme.orgregistry.quarkus.io の2つのレジストリが有効になります。レジストリの順序は実際に重要です。Quarkusの開発ツールがユーザーの要求に応じてエクステンションを探す場合、レジストリは設定された順、つまりリストの上から下に向かって検索されます。最初に見つかったエクステンションやプラットフォームは、ユーザーが好むものとして扱われます。

registry.quarkus.io はデフォルトのレジストリで、通常は明示的に設定する必要はありませんが、ユーザーがカスタムレジストリリストを提供し、その中に registry.quarkus.io が含まれていない場合は、 registry.quarkus.io は有効になり ません

たとえば、以下は、デフォルトの registry.quarkus.ioレジストリをカスタムのものに置き換えるレジストリクライアント設定です。

registries:
- registry.acme.org

レジストリキャッシュ更新ポリシーの調整

Usually, a Quarkus extension registry will be implemented as a Maven snapshot repository. The platform and extension catalogs resolved from the registry as Maven artifacts will be cached in the user’s local Maven repository. The platform and extension catalogs are actually SNAPSHOT artifacts that are periodically checked for updates by the registry client. The default registry interval to check for updates matches the default value of the Maven’s updatePolicy for snapshot repositories and is daily. This default can be overridden in the registry configuration, for example:

registries:
- registry.acme.org:
    update-policy: "always"
- registry.quarkus.io

上記の例では、 registry.acme.org レジストリは、カタログ要求ごとにカタログの更新がチェックされ、 registry.quarkus.io レジストリは、1日1回(その日の最初のカタログ要求時)にカタログの更新がチェックされます。

以下がレジストリの update-policy の値の選択肢の完全なリストです。

  • always- カタログ要求のたびに更新情報を確認する

  • daily(デフォルト) - 1日1回、最初のカタログ要求時に、カタログの更新をチェック

  • interval:X (Xは整数、分単位) - 分単位のカスタム間隔

  • never - カタログを一度解決すると、更新をチェックしない

設定でレジストリを無効化

設定ファイルに記載されているすべてのレジストリは、デフォルトで有効になっています。その設定に enabled: false を追加することで、レジストリを無効にすることができます。例えば、以下のようになります。

registries:
- registry.acme.org
- registry.quarkus.io:
    enabled: false

上記の設定では、 registry.acme.org のみが有効です。上記の設定は、以下と同等です。

registries:
- registry.acme.org

デバッグモードの有効化

レジストリクライアントは、デフォルトでは多くの情報をログ出力していません。しかし、舞台裏でMavenリポジトリから様々なアーティファクトを解決します。アーティファクトの転送やその他のデバッグ関連のメッセージをログに記録したい場合は、設定でデバッグモードを有効にすることができます。例えば、以下のようになります。

debug: true
registries:
- registry.acme.org
- registry.quarkus.io

Overriding a registry URL

There may be situations where the URL of the registry changes, however the ID needs to be the same (because the Maven coordinates are queried). To override the registry URL, add the following:

registries:
- registry.acme.org
- registry.quarkus.io:
    maven:
      repository:
        url: https://internal.registry.acme.org/maven

Nexusリポジトリプロキシとして登録する方法

QuarkusエクステンションレジストリをNexusリポジトリプロキシとして登録できます。これらの操作を行うには、管理者である必要があります。

Nexus 2.x

いくつかのオプションを設定する必要があります。

  • Repository PolicySnapshot に設定

  • Download Remote Indexes を無効化;

  • Allow File Browsing を無効化;

  • Include in Search の無効化.

以下は、その例です。

Nexus リポジトリマネージャ: プロキシリポジトリの追加

Nexus Repository Proxy

Nexus 3.x

Nexus Repository Proxy