Hudsonのホームディレクトリを変更する

Jenkins CI

はじめに

HudsonをWindowsサービスとして起動した場合に、Hudsonがシステム環境変数で設定した「HUDSON_HOME」を使用していないように見受けられたため、「HUDSON_HOME」の決定要素と決定順序について調査し、変更する際の一助になればと思いまとめました。
「HUDSON_HOME」の決定方法は、Administering Hudson - HUDSON_HOMEディレクトリに記載されていますが、以下はこの内容にWindows環境向けの情報を加筆したものになります。


以下では、Hudsonの起動方法の違いを簡易的に表現するためのアイコンを用います。
   : Hudsonをコマンドシェルから起動することを表します
   : HudsonをWindowsのサービスとして起動することを表します
   : HudsonをTomcatに配備して起動することを表します

HUDSON_HOMEディレクトリの決定要素

HUDSON_HOMEディレクトリの決定要素を並べると、次の通りになります。

  • (A) : %USERPROFILE%\.hudson
  • (B) : 環境変数に設定した「HUDSON_HOME」
  • (C) : 「hudson.exe」が置かれているディレクトリ
  • (D) : システムプロパティに設定した「HUDSON_HOME」
  • (E) : JNDI変数に設定した「HUDSON_HOME」

「hudson.exe」は、HudsonをWindowsサービスとしてインストールしたときに作成されるサービス制御用のプログラムです。

HUDSON_HOMEディレクトリの決定順序

決定要素、決定順序、Hudsonの起動方法の関係をまとめると、次の通りになります。

決定要素 決定順序
(A)
 デフォルト
使用可
使用可
使用可
(B)
 (A)より優先
使用可
使用可
使用可
(C)
 (B)より優先
使用不可
使用可
使用不可
(D)
 (C)より優先
使用可
使用可
使用可
(E)
 (D)より優先
使用不可
使用不可
使用可

より局所的に適用できる設定が優先される仕組みになっています。Hudsonの起動方法と環境の構築プランに応じて、適用する決定要素を決めてください。

なお、の場合は、通常「hudson.warの内容」が配備されるディレクトリと「HUDSON_HOME」ディレクトリとが異なります。これに対して、との場合は、「HUDSON_HOME」ディレクトリ内の「war」ディレクトリの中に「hudson.warの内容」が配備されます。この違いが、JNDI変数の使用可否の違いを生み出しているものと思われます。

決定要素別のHUDSON_HOMEディレクトリの設定方法

(A)の設定方法

デフォルト値です。設定不要です。

(B)の設定方法

システム環境変数として設定するか、コマンドシェルの中で個別に設定します。

例:
> SET HUDSON_HOME=C:\Hudson\Home
(C)の設定方法

の場合にのみ使用されます。設定不要です。
ただし、厳密にはHudsonをWindowsサービスとしてインストールしたディレクトリの中に、「hudson.exe」と「hudson.xml」が作成され、この「hudson.xml」の中に次のエントリがあるので、「hudson.exe」が置かれているディレクトリが使用されます。

  <env name="HUDSON_HOME" value="%BASE%"/>
※「%BASE%」が「hudson.exe が置かれているディレクトリ」を表します。

補足:「%BASE%」を「C:\Hudson\Home」などに変更することもできます。ただし、「hudson.exeが置かれているディレクトリ」と「HUDSON_HOMEディレクトリ」は一致しているべきなので、この変更方法はお勧めしません。

(D)の設定方法

の場合は、次のように設定します。

例:
> java -DHUDSON_HOME=C:\Hudson\Home -jar hudson.war

注意: -DHUDSON_HOME=... は、-jar hudson.war より前に記述してください。


の場合は、「hudson.xml」の中で次のように設定します。

  <executable>java</executable>
  <arguments>-Xrs -Xmx256m -DHUDSON_HOME=C:\Hudson\Home -Dhudson.lifecycle=hudson.lifecycle.WindowsServiceLifecycle -jar "%BASE%\hudson.war" --httpPort=8080</arguments>

注意: -DHUDSON_HOME=... は、-jar "%BASE%\hudson.war" より前に記述してください。
注意: 設定後は、サービスを再起動してください。
補足:「hudson.exeが置かれているディレクトリ」と「HUDSON_HOMEディレクトリ」は一致しているべきなので、この変更方法はお勧めしません。


の場合は、[スタート] > [すべてのプログラム] > [Apache Tomcat 6.0] > [Configure Tomcat]で表示される設定画面の[Java] > [Java Options:]の中で次のように設定します。

注意: 設定後は、Tomcatを再起動してください。

(E)の設定方法

に配備されたHudsonの「webapps\hudson\WEB-INF\web.xml」の中で次のように設定します。

  <!-- if specified, this value is used as the Hudson home directory -->
  <env-entry>
    <env-entry-name>HUDSON_HOME</env-entry-name>
    <env-entry-type>java.lang.String</env-entry-type>
    <env-entry-value>C:\Hudson\Home</env-entry-value>
  </env-entry>

注意: Hudsonをバージョンアップする場合、「webapps\hudson」ディレクトリの内容を新しい「hudson.war」の内容で刷新することになります。「webapps\hudson\WEB-INF\web.xml」の内容を変更した場合は、バージョンアップ後に再度上記の設定を行ってください。

おわりに

トラブルシューティングを目的として一時的にHUDSON_HOMEディレクトリを切り替えたい場合や、HUDSON_HOMEディレクトリを複数個使用して同一マシン上に複数個のHudsonを起動させたい場合に、上記が役立つかもしれません。

実際の動作を確認した上で書き起こしていますが、誤りなどありましたら、早急に修正しますのでご指摘ください。