Installing JIRA on Tomcat 6.0

This section describes how to install JIRA on Tomcat 6.0, a popular open-source server from the Apache Jakarta project.

Tomcat can be downloaded from the Apache site.

このページの内容

開始する前に

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

• All versions of Tomcat effectively leak memory by caching JSPs, which can result in OutOfMemoryErrors if large pages (eg. RSS or Excel) are requested. There is a flag you should set to disable this caching.
• If you are using version 6.0.13 or higher of Tomcat 6, with a MySQL database, you must set up Tomcat to survive connection closures. These versions of Tomcat have been noted to exhibit problems maintaining connections to MySQL databases. Please read this document for details on the changes required.
• 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).

  We also strongly recommend that you do not deploy multiple Atlassian applications in a single Tomcat container for a number of practical reasons. Firstly, you will need to shut down Tomcat to upgrade any application and secondly, if one application crashes, the other applications running in the Tomcat container will be inaccessible.

• The JIRA 'Standalone' download is JIRA preconfigured with a copy of Tomcat 6.0.20 (for JIRA 4.3.0) or Tomcat 6.0.32 (for JIRA 4.3.1 and later). If you have JIRA Standalone, you don't need to follow the steps below.

1. Unpack JIRA

2. JIRA の設定

2.1 Database Connection

JIRA needs to be told what type of database you'll be using. The database is specified in $JIRA_INSTALL/edit-webapp/WEB-INF/classes/entityengine.xml . Locate the <datasource> tag near the bottom, and change the field-type-name attribute value. See the relevant setup guide for your database to find out what value should be used for field-type-name:

          <datasource name="defaultDS"
          field-type-name="hsql"
          schema-name="PUBLIC"
          helper-class="org.ofbiz.core.entity.GenericHelperDAO"
          check-on-start="true"
          use-foreign-keys="false"
          use-foreign-key-indices="false"
          check-fks-on-start="false"
          check-fk-indices-on-start="false"
          add-missing-on-start="true">
          <jndi-jdbc jndi-server-name="default"
          jndi-name="java:comp/env/jdbc/JiraDS" />
        </datasource>

For PostgreSQL 7.3+, you also need to set a schema-name attribute. Refer to Connecting JIRA to PostgreSQL for details.

Also in entityengine.xml , 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>

More details on JIRA's database access layer are available on the EntityEngine configuration page.

2.2 JIRA ホーム

3. JIRA のビルド

Now build JIRA by typing build (Windows) or ./build.sh (Unix) on the command line in the $JIRA_INSTALL directory. This will produce the deployable WAR file in the $JIRA_INSTALL/dist-tomcat/tomcat-6 directory.

4. Update Tomcat Libraries

Tomcat does not come with some libraries required to run JIRA. To fix this, download http://downloads.atlassian.com/software/jira/downloads/jira-jars-tomcat-distribution-4.3-tomcat-6x.zip and copy the contained jars to Tomcat's lib/ directory. (Be sure to remove existing versions of these JAR before copying the new ones.)

• In particular, to prevent exceptions related to logging, please ensure that commons-logging-1.0.4.jar and log4j-1.2.15.jar are present in Tomcat's /lib/ directory. Also ensure that these files are not present in Tomcat's webapps/jira/WEB-INF/lib directory.

Additionally, if you are running Sun's distribution of Tomcat, download tomcat-dbcp.jar and copy it to the tomcat6/lib directory.

5. Tomcat の構成

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

1. Make a Catalina/localhost/ directory in Tomcat's conf/ directory.
2. Copy dist-tomcat/tomcat-6/jira.xml from the built JIRA distribution to your Tomcat's conf/Catalina/localhost/ directory.

3. Customise the copied jira.xml as follows:

   <Context path="/jira" docBase="path/to/atlassian-jira-4.1.war">
     <Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"
               username="sa"
               password=""
               driverClassName="org.hsqldb.jdbcDriver"
               url="jdbc:hsqldb:path/to/database/jiradb/"
               minEvictableIdleTimeMillis="4000"
               timeBetweenEvictionRunsMillis="5000"/>
   
     <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 directory.

   注意

   If you are not using hsqldb, make sure you comment out the minEvictableIdleTimeMillis and timeBetweenEvictionRunsMillis params, or JIRA will run slower than normal.

   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:\yourdb\tomcatdb). N.B. the last part of the path is the name of the database and is not a directory.The above example assumes you are using hsql (an in-memory database - a good choice for evaluation purposes). Here is an example using MySQL:

   <Context path="/jira" docBase="path/to/atlassian-jira-4.0.war">
     <Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"
       username="jirauser"
       password="mypassword"
       driverClassName="com.mysql.jdbc.Driver"
       url="jdbc:mysql://localhost/jiradb?useUnicode=true&amp;characterEncoding=UTF8"
       maxActive="20"
       validationQuery="select 1"/>
     <Resource name="UserTransaction" auth="Container" type="javax.transaction.UserTransaction"
       factory="org.objectweb.jotm.UserTransactionFactory"
       jotm.timeout="60"/>
     <Manager pathname=""/>
   </Context>
   

   Notice the lack of minEvictableIdleTimeMillis and timeBetweenEvictionRunsMillis parameters — those should only be used with hsql.

4. If using a different database than hsql,
   • copy the JDBC driver jar to CATALINA_HOME/lib/ (see the database configuration guide ); and
   • ensure you have updated the field-type-name ( see above ).

6. Modify Tomcat server.xml

In order for JIRA to correctly display internationalised characters in user and group names you need to modify your Tomcat distributions conf/server.xml file. You need to set the property URIEncoding="UTF-8" within the connector definition for your http protocol. The connector block should look very much like this:

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

You should modify the block to contain the addition of the URIEncoding property:

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

7. Fix Tomcat memory settings

Tomcat has a memory leak where large JSP page requests can fill up memory. JIRA also requires more memory than what is available by default or you may see OutOfMemory errors. Finally there's also a parameter that needs to be set in order for the JIRA mail handler to work correctly with emails from RFC 2231-compliant mail clients. To avoid any of these issues:

Windows の場合

If you haven´t installed Tomcat as a service, edit Tomcat's bin/setenv.bat(create it if it does not exist) and set:

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

if you running Tomcat 6 as service, right click the tomcat system tray icon and select "Configure..."

Now click on the Java tab and enter the following values

下記スクリーンショットに類似した設定になるはずです:

Linux の場合

Edit Tomcat's bin/setenv.sh (create it if it does not exist) and set:

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

For other environments, and for more info on memory settings, see the memory settings page.

8. Tomcat の起動

JIRA should now be ready to run in Tomcat. To start using JIRA, first start (or restart) the Tomcat server with Tomcat's bin/startup.(sh|bat) scripts, and point your browser to http://localhost:8080/jira

You should now see the Setup Wizard, which will take you through the brief setup procedure.

トラブルシューティング

It is easy to make a mistake in this process, and even more so if you are trying to connect to a database other than hsqldb. First, check that you have followed the process described above:

• If you are using an external database (not hsqldb), have you set the field-type-name attribute in $JIRA_INSTALL/edit-webapp/WEB-INF/classes/entityengine.xml ? ( step 2 )
• Have you previously started JIRA with an incorrect field-type-name value? If so, the database schema would have been created incorrectly.
• If you have made changes to $JIRA_INSTALL/edit-webapp/WEB-INF/classes/entityengine.xml ( step 2 ) and re-run the build script ( step 3 ), but your changes are not being picked up, delete the Tomcat webapps/jira directory, then restart JIRA. It would seem that in some circumstances Tomcat does not correctly re-expand the web application.
• Have you copied the extra Tomcat jars ( step 4 )? Check if you have CATALINA_HOME/lib/objectweb-datasource-1.4.3.jar present.
• If using an external database, did you copy the JDBC driver jar to CATALINA_HOME/lib/? (Refer to the Connecting JIRA to a Database section for more information)
• Is the path to the .war file in conf/Catalina/localhost/jira.xml correct?
• Have you copied the .war file to Tomcat's webapps/ directory? This is almost guaranteed to cause problems - please move it elsewhere, and delete any JIRA subdirectories created in webapps/ from previous Tomcat starts.
• Have you configured JIRA centrally in conf/server.xml instead of in conf/Catalina/localhost/jira.xml ? This is fine, but then be sure you don't also have a conf/Catalina/localhost/jira.xml 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 the logs/ directory. On Linux/Unix, 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 (eg OutOfMemoryError), you may wish to set the system property -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true in setenv.sh / setenv.bat. This property is only valid for Tomcat 5.5.15 and later. For more information please see JRA-10145.
• If the connection to your MySQL database is dropping, you will need to set up Tomcat to survive connection closures.
• Please note: The build.xml file is an Ant file, which when invoked with the build.(sh|bat) script, will construct a deployable webapp. The build.xml file does this by copying the contents of the webapp/ directory, and overwriting it with the contents of edit-webapp/. Thus, never edit files in the webapp/ directory! If a file needs editing, first copy it from webapp/path/to/file to edit-webapp/path/to/file, and edit it there.

If you're stuck, please raise a support request, and attach your logs, configuration files, plus anything else relevant, and we'll get back to you as soon as possible.