カスタム Maven 設定ファイルの使用

最終更新日 2024年05月30日(木)

Maven の settings.xml​ ファイルでは、さまざまな方法で Maven の実行を設定する​値が定義されます。最も一般的には、ローカルリポジトリの場所、代替リモートリポジトリサーバー、プライベートリポジトリの認証情報を定義するために使用されます。この記事では、Heroku にデプロイされた Java アプリケーションにカスタム設定ファイルを追加する方法について学習します。

すでに Java アプリケーションがある場合は、それをこの例で使用できます。それ以外の場合は、「Heroku スターターガイド (Java)​」の記事から単純なアプリケーションを作成します。

カスタム設定ファイルの作成

アプリケーションのルートディレクトリに settings.xml​ という名前のファイルが存在する場合、Heroku の Java サポート​では、コンパイル時に自動的にそれを使用して Maven を設定します。

これを示すには、Java プロジェクトのルートディレクトリに settings.xml​ ファイルを追加し、その中に次のコードを記述します。

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <profiles>
    <profile>
      <id>jboss-public</id>
      <repositories>
        <repository>
          <id>jboss-public-repository</id>
          <name>JBoss Public Maven Repository Group</name>
          <url>http://repository.jboss.org/nexus/content/groups/public/</url>
        </repository>
      </repositories>
    </profile>
  </profiles>

  <activeProfiles>
    <activeProfile>jboss-public</activeProfile>
  </activeProfiles>
</settings>

これは、Maven に、アプリケーションの依存関係を解決するときに https://repository.jboss.org​ でホストされているリポジトリを検索するよう指示します。このリポジトリは、HTTP または HTTPS でアドレス指定する必要があります。file://​のアドレスが必要な場合は、管理されていない依存関係の記事​を参照してください。

これらの設定は、任意の Maven タスクに -s​ オプションを追加することによってローカルでテストできます。ただし、まずプロジェクトに新しい依存関係を追加する必要があります。jboss.web.servlet-api​ライブラリは、JBoss リポジトリでのみ入手できるため、適切な例です。プロジェクトの pom.xml​ に次の要素を追加します。

<dependency>
  <groupId>jboss.web</groupId>
  <artifactId>servlet-api</artifactId>
  <version>2.1.0.GA</version>
</dependency>

ここで、次のコマンドを実行すると、Maven によりアーティファクトがダウンロードされます。

$ mvn -s settings.xml dependency:list
[INFO] Scanning for projects...
...
Downloading: http://repository.jboss.org/nexus/content/groups/public/jboss/web/servlet-api/2.1.0.GA/servlet-api-2.1.0.GA.pom
Downloaded: http://repository.jboss.org/nexus/content/groups/public/jboss/web/servlet-api/2.1.0.GA/servlet-api-2.1.0.GA.pom (195 B at 0.2 KB/sec)
Downloading: http://repository.jboss.org/nexus/content/groups/public/jboss/web/servlet-api/2.1.0.GA/servlet-api-2.1.0.GA.jar
Downloaded: http://repository.jboss.org/nexus/content/groups/public/jboss/web/servlet-api/2.1.0.GA/servlet-api-2.1.0.GA.jar (84 KB at 90.8 KB/sec)

カスタム設定ファイルを使用していない場合、ビルドは失敗し、Maven で次のようなエラーが生成されます。

Downloading: http://repo.maven.apache.org/maven2/jboss/web/servlet-api/2.1.0.GA/servlet-api-2.1.0.GA.pom
[WARNING] The POM for jboss.web:servlet-api:jar:2.1.0.GA is missing, no dependency information available
Downloading: http://repo.maven.apache.org/maven2/jboss/web/servlet-api/2.1.0.GA/servlet-api-2.1.0.GA.jar
...
[ERROR] Failed to execute goal on project helloworld: Could not resolve dependencies for project com.example:helloworld:jar:1.0-SNAPSHOT: Could not find artifact jboss.web:servlet-api:jar:2.1.0.GA in central (http://repo.maven.apache.org/maven2) -> [Help 1]

ここで、settings.xml​ と pom.xml​ の変更を Git リポジトリに追加し、次のように Heroku にデプロイします。

$ git add pom.xml settings.xml
$ git commit -m "adding jboss servlet-api dependency"
$ git push heroku master

dyno で Maven を実行すると、出力はローカルの場合と同じになります。Heroku によってルートディレクトリから settings.xml​ ファイルが検出され、-s​ オプションが Maven コマンドに追加されるため、これは問題ありません。次に、この場所をカスタマイズする方法について説明します。

MAVEN_SETTINGS_​PATH 環境設定の定義

settings.xml​ ファイルをルートディレクトリに置かない場合や、複数の設定を頻繁に切り替えて使い分ける予定の場合、カスタムの場所に設定ファイルを置くことができます。Heroku では、MAVEN_SETTINGS_PATH​ 環境設定でこの機能を提供します。

この機能の使用例として、既存の settings.xml​ を support/​ ディレクトリに移動し、次のように名前を変更します。

$ mkdir -p support
$ git mv settings.xml support/jboss-settings.xml

次に、ルートディレクトリに相対的な MAVEN_SETTINGS_PATH​ を定義して、設定ファイルが配置されている場所を Heroku に通知します。

$ heroku config:set MAVEN_SETTINGS_PATH=support/jboss-settings.xml

変更をテストする前に、servlet-api のバージョンを増分して、Maven がそれを強制的にもう一度ダウンロードするようにします。pom.xml​内の依存関係をバージョン 2.1.1.GA​ に変更します。これは次のようになります。

<dependency>
  <groupId>jboss.web</groupId>
  <artifactId>servlet-api</artifactId>
  <version>2.1.1.GA</version>
</dependency>

ここで、変更を Git にコミットし、次のように Heroku に再デプロイします。

$ git commit -am "moved settings file and incremented servlet-api version"
$ git push heroku master

Maven はもう一度、JBoss リポジトリから依存関係をダウンロードします。これにより、少し柔軟性が向上しますが、プロジェクト内のカスタムの場所が十分でない場合があります。このファイルをコードベースとは完全に別にしておくこともできます。

MAVEN_SETTINGS_​URL 環境設定の定義

MAVEN_SETTINGS_URL​ 環境設定が定義されている場合、Heroku はこのファイルを特定の場所にダウンロードし、それを使用して Maven を設定します。これを示す前に、前の例で定義した環境設定を解除する必要があります。それは、両方の環境設定が設定されている場合は、こちらが優先されるためです。

$ heroku config:unset MAVEN_SETTINGS_PATH

ここで、Torquebox Application Server コードベースなどの一般に入手可能なソースの settings.xml​ を使用できます。環境設定を次のように設定します。

$ heroku config:set MAVEN_SETTINGS_URL="https://raw.githubusercontent.com/torquebox/torquebox/master/support/settings.xml"

前と同様に、servlet-api のバージョンを 2.1.2.GA​ に増分し、pom.xml​ を Git リポジトリに追加し、変更をコミットして Heroku に再デプロイします。Maven は、前と同様に、JBoss リポジトリから新しいアーティファクトをダウンロードします。

JBoss リポジトリは、公開されているため便利です。アクセスするためにパスワードは必要ありません。ただし、すべてのリポジトリがいつも開いているわけではありません。

パスワードで保護されたリポジトリの使用

一部のアーティファクトリポジトリは、アクセスするためにユーザー名とパスワードが必要です。そのリポジトリは多くの場合、内部アーティファクトをホストしているプライベートサーバーです。この場合は、リポジトリにアクセスするための資格情報を settings.xml​ で指定する必要があります。これは、そのファイルが Git リポジトリにチェックインされていると問題になる場合があります。

環境変数は Maven 設定ファイルで検出できます。${env.ENV_VAR}​(ENV_VAR​ は変数の名前) の形式のトークンはすべて、関連付けられた環境変数の値に解決されます。そのため、プライベート Maven リポジトリのパスワードを Heroku 環境設定として次のように定義できます。

$ heroku config:set MAVEN_REPO_PASSWORD="deployment123"

その後、<activeProfile>​ 内の <repository>​ 要素の <id>​ に一致する <server>​ 要素を作成することにより、settings.xml​ ファイルでこの変数を使用できます。

<servers>
  <server>
    <id>my-private-repo</id>
    <username>deployment</username>
    <password>${env.MAVEN_REPO_PASSWORD}</password>
  </server>
</servers>

これを示すには、プライベート Maven リポジトリが必要になります。このリポジトリは、Sonatype Nexus​ をダウンロードし、リポジトリをセキュリティ保護するための手順​に従うことによって作成できます。または、JFrog Artifactory​ のホストされたバージョンを使用できます。

どちらの場合も、プライベートリポジトリを使用すると内部アーティファクトを公開し、それを Heroku アプリケーションに含めることができます。

設定ファイルを使用した Maven のカスタマイズについての詳細は、Apache.org の「Maven Settings Reference​」(Maven 設定のリファレンス) を参照してください。