Installing JIRA on Tomcat 6.0

This guide describes how to install the JIRA WAR distribution on Tomcat 6.0, a popular open-source server from the Apache project. Tomcat can be downloaded from the Apache site.

JIRA installations which have been installed using the 'Windows Installer', 'Linux Installer' or from an 'Archive File' are pre-configured to use their own dedicated Tomcat application server. To install JIRA using one of these 'recommended' distributions, follow the Installing JIRA guide instead of the instructions below.

はじめる前に

Please read the following important notes before you begin installing JIRA on Tomcat 6.0:

• Tomcat 6.0.24 には 重大なバグ があります。バージョン 6.0.32 を使用してください。
• Deploying multiple Atlassian applications in a single Tomcat container is not supported. We do not test this configuration and upgrading any of the applications (even for point releases) is likely to break it. There are also a number of known issues with this configuration (see this FAQ for more information).

  弊社では、多くの実用的な理由から、複数のアトラシアンアプリケーションを単一の Tomcat コンテナーにデプロイするサポートは行っておりません。第一に、アプリケーションをアップグレードするには Tomcat をシャットダウンする必要があります。第二に、１つのアプリケーションがクラッシュすると、その Tomcat コンテナーで実行中のその他のアプリケーションにアクセスできなくなります。

  Finally, we recommend not deploying any other applications in the same Tomcat container that runs JIRA, especially if these other applications have large memory requirements or require additional libraries in Tomcat's lib subdirectory.

On this page:

1. JIRA アーカイブのダウンロードと解凍

Download the JIRA WAR distribution archive from the JIRA Download page and extract its contents using a tool such as 7-zip for Windows or Linux's unzip or GNU tar tools.
You may need to click the 'Show All' link on the download page to reveal the WAR distribution.

Avoid using Windows' built-in file extraction tool! This tool silently fails to extract files with long names (see JRA-2153). Other users have also reported problems with WinRAR.

Avoid using Solaris' default tar utility! Please use GNU tar on this operating system to extract JIRA, as GNU tar handles long filenames better.

解凍されたディレクトリは、その後 JIRA インストレーションディレクトリとして参照されます。

例えば以下の方法で、JIRA を実行するための専用のユーザーを作成します。これにより、このユーザーが悪用されたときの影響が限定的になります。

• オペレーティング システムが *nix ベース (Linux や Solaris など) の場合は、コンソールで次のように入力します。
  $ sudo /usr/sbin/useradd --create-home --comment "Account for running JIRA" --shell /bin/bash jira

• オペレーティングシステムが Windows の場合
  1. 以下のいずれかの方法で専用のユーザーを作成します
     • Typing the following at the Windows command line:
       > net user jira mypassword /add /comment:"Account for running JIRA"
       (This creates a user account with user name 'jira' and password 'mypassword'. You should choose your own password.)
     • Windows の 'Computer Management' コンソールを開いて、ご自身の使いたいパスワードで 'jira' ユーザーを作成します
  2. (Optional) Use the Windows 'Computer Management' console to remove the 'jira' user's membership of all unnecessary Windows groups, such as the default 'Users' group.
     If Windows is operating under a Microsoft Active Directory, ask your Active Directory administrator to create your 'jira' account (with no prior privileges).

To maximise security, ensure that this user can only write to the logs, temp and work directories of your application server (Apache Tomcat) installation and your JIRA Home Directory.

2. JIRA の設定

2.1 Customising your JIRA installation directory files

(この節の内容は必須ではなく、技術者のみに推奨します)

2.1.1 How to customise files in your JIRA installation directory

If you wish to customise any files in the <jira-application-dir> (i.e. the webapp subdirectory) of your JIRA Installation Directory, please perform them in the sibling edit-webapp subdirectory only.

To edit a file within the webapp subdirectory, first copy it from the webapp/path/to/file subdirectory to the edit-webapp/path/to/file subdirectory of your JIRA Installation Directory and edit it in the latter location.

When building JIRA (below), .war files are constructed based on file contents copied from the webapp subdirectory of your JIRA Installation Directory, which are overwritten by file contents from the sibling edit-webapp directory. Thus, never edit files within this webapp directory!

Be aware that the more files you customise in your JIRA Installation Directory, the more difficult it will be to upgrade JIRA or migrate JIRA to another server, as your customisations will need to be migrated manually over to your new JIRA installation.

2.1.2 Configuring the entityengine.xml file

Ensure that the Transaction Factory has been specified correctly in JIRA's entityengine.xml file. For more information, see Configuring the Entity Engine for JIRA.

• In the entityengine.xml file (located in edit-webapp/WEB-INF/classes/ of the JIRA Installation Directory), ensure the <transaction-factory>...</transaction-factory> tag contains:

  <transaction-factory class="org.ofbiz.core.entity.transaction.JNDIFactory">
      <user-transaction-jndi jndi-server-name="default" jndi-name="java:comp/env/UserTransaction"/>
      <transaction-manager-jndi jndi-server-name="default" jndi-name="java:comp/env/UserTransaction"/>
  </transaction-factory>
  

  JIRA データベース アクセス層の設定に関する詳細は、Configuring the Entity Engine for JIRA を参照してください。

2.2 JIRA ホーム

• Edit the jira-application.properties file and set the value of the 'jira.home' property to the desired location for your JIRA Home Directory. If you are specifying this location's path on Windows, use double back-slashes ("\") between subdirectories. For example, X:\\path\\to\\JIRA\‌\Home
  See the JIRA Installation Directory page to find where this file is located.
• Set an environment variable named JIRA_HOME in your operating system whose value is the location of your JIRA Home Directory. To do this:

  • Windows の場合は、次のいずれかを実行してください
    
    • Windows ユーザー インターフェイス（一般的に「マイコンピュータ」または「コンピュータ」）からこの環境変数を設定します。
    • コマンド プロンプト画面で、以下のコマンドを入力（自分の JIRA Home パスを使用する）した後、コマンド プロンプトから JIRA を実行します。
      
      • set JIRA_HOME=X:\path\to\JIRA\Home
        Please set your JIRA_HOME  environment variable value using this format, where:
        
        • X は Jira ホーム ディレクトリが格納されているドライブの文字
        • イコール ("=") の前後にスペースは不要
    • JIRA の起動に使用したバッチ ファイルで上記のコマンドを設定します。
  • Linux/Solaris では、以下のいずれかを実行してください。
    
    • JIRA を起動する前にシェル／コンソールプロンプトで以下のコマンドを実行する（ご自身の JIRA ホームディレクトリを指定して）
      
      • export JIRA_HOME=/path/to/jira/home
    • JIRA を起動するときに使うスクリプトに上記のコマンドを追加する

For more information about setting up your JIRA Home Directory, please see Setting your JIRA Home Directory.

3. JIRA のビルド

Now build JIRA by running build.bat (Windows) or ./build.sh (Linux/Solaris) on the command line in the JIRA Installation Directory. This will produce the deployable WAR file in the dist-tomcat/tomcat-6 subdirectory of the JIRA Installation Directory.

4. JIRA 稼働に必要な Tomcat インストールの ライブラリのアップデート

4.1 JDBC ドライバー

JIRA がデータベースと通信できるようにするには、Tomcat インストールに適切な JDBC ドライバーが必要です。この JDBC ドライバーを Tomcat に追加するには、適切な説明を次から選び、参照してください:

• PostgreSQL JDBC ドライバーを Tomcat にコピーします。
• MySQL JDBC ドライバーを Tomcat にコピーします。
• Oracle JDBC ドライバーを Tomcat にコピーします。
• SQL Server 2005 JDBC ドライバーを Tomcat にコピーします。
• SQL Server 2008 JDBC ドライバーを Tomcat にコピーします。
• Copy the HSQL JDBC Driver to Tomcat
  If you intend to use the HSQL database, the HSQL JDBC driver is already included with the other JIRA library files that will be added to Tomcat in the following step.

4.2 Tomcat のその他のライブラリ

Tomcat does not come with some libraries required to run JIRA. To fix this, download http://www.atlassian.com/software/jira/downloads/binary/jira-jars-tomcat-distribution-5.1-tomcat-6x.zip extract and copy the .jar library files from this archive to the lib subdirectory of your Tomcat installation directory.

注意:

• Be sure to remove existing versions of these .jar library files before copying over new ones.

• To prevent exceptions related to logging, please ensure that the following files are present in Tomcat's lib directory. Also ensure that these files are not present in the webapp/jira/WEB-INF/lib subdirectory of the JIRA Installation Directory. If any of the following files are present in the webapp/jira/WEB-INF/lib subdirectory, remove them and rebuild the deployable JIRA WAR file as described in the previous step (above).

  ファイル
  jcl-over-slf4j-x.y.z.jar
  jul-to-slf4j-x.y.z.jar
  log4j-x.y.z.jar
  slf4j-api-x.y.z.jar
  slf4j-log4j12-x-y-z.jar

5. Tomcat に JIRA のコンテキストを設定する

A JIRA 'context' now needs to be set up in Tomcat. To do this:

1. Create the directory structure conf/Catalina/localhost/ within your Tomcat installation directory.
2. Copy the jira.xml file from the etc subdirectory of your JIRA Installation Directory to the conf/Catalina/localhost subdirectory of your Tomcat installation directory (created in the previous step).

3. If necessary, customise the copied jira.xml file within your Tomcat installation — in particular, the value of the docBase attribute of the Contextelement:

   <Context path="/jira" docBase="path/to/atlassian-jira-5.x.war" debug="0" useHttpOnly="true">
   
     <Resource name="UserTransaction" auth="Container" type="javax.transaction.UserTransaction"
       factory="org.objectweb.jotm.UserTransactionFactory" jotm.timeout="60"/>
     <Manager pathname=""/>
   
   </Context>
   

The paths (denoted as path/to/) will be correct by default, assuming you want to deploy the .war from the dist-tomcat/tomcat-6 subdirectory of your JIRA Installation Directory.

If you are installing in Windows, make sure that the paths you specify for the location of the WAR file and database are full paths with drive letters (e.g. C:\path\to\atlassian-jira-4.x.war).

6. Modify Tomcat's server.xml to handle internationalised characters correctly

In order for JIRA to correctly display internationalised characters in user and group names, you need to modify the conf/server.xml file in your Tomcat installation directory by specifying the URIEncoding="UTF-8" property within the connector definition for your HTTP protocol.

The connector definition is specified by the following element in your server.xml file:

<Connector port="8080" protocol="HTTP/1.1"
        connectionTimeout="20000"
        redirectPort="8443"/>

You should modify this element by specifying the URIEncoding="UTF-8" attribute:

<Connector port="8080" protocol="HTTP/1.1"
        connectionTimeout="20000"
        redirectPort="8443" URIEncoding="UTF-8"/>

注意:

• このプロパティはアプリケーション サーバーに対するコネクタ レベルで定義される必要があるので、この設定は、JIRA を起動しているアプリケーション サーバー インストールにデプロイされているその他すべての Web アプリケーションに影響を及ぼします。この設定は、他の Web アプリケーションに悪影響を及ぼすことはないはずですが、この点を留意してください。
• JIRA はこのプロパティ設定なしでも問題なく動作します。しかし、国際化文字を含むユーザー名やグループ名が作成されると問題が発生します。したがって、このプロパティの設定をお勧めします。

7. Tomcat のメモリとメール処理設定を修正

次の問題を回避するため、Tomcat ではメモリとメール処理設定を修正する必要があります:

• Tomcat effectively leaks memory by caching JSPs. This can result in OutOfMemoryError errors if large pages (such as RSS or Excel pages) are requested.
• JIRA requires more memory than what Tomcat provides by default. This may lead to OutOfMemory errors when running JIRA if these memory settings are not increased.
• For JIRA's mail handler to avoid problems with RFC 2231-compliant mail clients, set the mail.mime.decodeparameters startup parameter in Tomcat to true.

上記の問題を回避するには、下記にあるお使いの OS に対応する手順に従ってください。

Windows の場合

Tomcat がサービスとしてインストールされていない場合:

• Edit Tomcat's bin/setenv.batfile (or create this file if it does not exist) and add the following to this file:

  set CATALINA_OPTS=%CATALINA_OPTS% -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true -Dmail.mime.decodeparameters=true -Xms128m -Xmx512m -XX:MaxPermSize=256m
  

Tomcat がサービスとしてインストールされ、稼働中の場合:

1. Right-click Tomcat's system tray icon and select 'Configure' from the resulting popup menu, which opens the 'Apache Tomcat 6 Properties' dialog box:
   tomcat6a.JPG

2. このダイアログ ボックスで、Java タブをクリックし、次の値を指定します:

   フィールド	値
   Java Options (既存値に追加する)	-Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true -Dmail.mime.decodeparameters=true
   初期メモリプール	128
   最大メモリプール	512

   Your configuration should be similar to the screenshot below:
   tomcat6b.JPG

Linux/Solaris:

Edit Tomcat's bin/setenv.sh file (or create this file if it does not exist) and add the following to this file:

export CATALINA_OPTS="$CATALINA_OPTS -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true -Dmail.mime.decodeparameters=true -Xms128m -Xmx512m -XX:MaxPermSize=256m"

メモリ設定のその他の環境や詳細に関しては、Increasing JIRA Memory を参照してください。

8. Tomcat の起動

(Tomcat がサービスとして稼働してない場合にのみ必要)

JIRA should now be ready to run in Tomcat. To start up JIRA, start (or restart) the Tomcat server with Tomcat's bin/startup.sh or bin/startup.bat scripts.

9. セットアップ ウィザードの実行

ブラウザーで次を参照します

セットアップ ウィザード が表示されるはずです。ここで、データベース接続の設定手順などの JIRA のセットアップができます。

トラブルシューティング

このインストールは失敗しやすいものです。まず、上記に説明された手順に従ったかどうか確認してください:

• Have you have made changes to edit-webapp/WEB-INF/classes/entityengine.xml in your JIRA Installation Directory (step 2 above) and re-run the build script (step 3 above), but your entityengine.xml changes were not picked up? If so, delete the webapps/jira subdirectory of your Tomcat installation directory and then restart JIRA. (In some circumstances, Tomcat does not correctly re-expand the web application.)
• If you are using an external database, did you copy the correct JDBC driver jar file to the lib subdirectory of your Tomcat installation directory? (Refer to step 4 above.)
• Have you updated your Tomcat installation's libraries for JIRA by copying across the additional jar files downloaded in step 4 above? Check if objectweb-datasource-x.y.z.jar present in the lib subdirectory of Tomcat's installation directory.
• Is the path to your built .war file within conf/Catalina/localhost/jira.xml of your Tomcat installation directory correct? (Refer to step 5 above.)
• Have you copied your built .war file to Tomcat's webapps directory? This is almost guaranteed to cause problems - please move this .war file elsewhere and delete any JIRA subdirectories created in Tomcat's webapps directory which Tomcat may have created (after Tomcat is initially started).
• Have you configured JIRA's context and other custom settings centrally in Tomcat's conf/server.xml file instead of the conf/Catalina/localhost/jira.xml file of your Tomcat installation directory? Although this is fine, be sure that you do not also have a conf/Catalina/localhost/jira.xml file present.
• The log files are usually vital to debugging problems. On Windows, these will appear in the console window that loads when running startup.bat, or in one of the log files in Tomcat's logs directory. On Linux/Solaris, logs will appear in a log file in logs, usually logs/* (not just logs/catalina.out). Check the log file for errors after startup.
• If you experience high memory usage / memory leaks (e.g. OutOfMemoryError), you may wish to set the system property -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true in the setenv.sh / setenv.bat file. For more information please see JRA-10145. (Refer to step 7 above.)
• データベースへの接続が切断されがちな場合 (特に、MySQL との間で)、Tomcat に コネクション切断の問題を乗り越える ための設定をする必要があります。
• Please be aware: The build.xml file is an Ant file, which when invoked with the build.sh / build.bat script, will construct deployable web application archive (.war) files (for supported application servers). The build.xml file copies the contents of the webapp subdirectory of your JIRA Installation Directory and overwrites it with the contents of the sibling edit-webapp directory, when constructing its .war files. Thus, unless otherwise requested, never edit files within this webapp directory!
  If a file needs editing, first copy it from webapp/path/to/file to edit-webapp/path/to/file subdirectories of your JIRA Installation Directory and edit it in the latter location.

If you are stuck, then please consider installing one of the 'recommended' distributions of JIRA.

ユーザーから寄せられた注意点

Do you have experiences to share with Tomcat 6.0.x and JIRA? We welcome your thoughts. Please see the user-contributed Tomcat 6.0.x notes.