This page last changed on Jun 15, 2009 by rosie@atlassian.com.

This section describes how to install JIRA on Tomcat 4.0.x, an open-source server from the Apache Jakarta project.

These instructions have been tested with Tomcat 4.0.6. JIRA should work on all 4.0.x releases except 4.0.4. Also, problems with some pages have been reported with 4.0.3.

There is a different setup guide for Tomcat 4.1. The main difference with 4.1 is:

  • Tomcat 4.0 does not include commons-logging.jar in the common/lib/ directory, so it must be manually added.
  • 4.0 does not support XML config files in the webapp/ directory, so conf/server.xml must be modified.

If you have not yet downloaded Tomcat, we recommend you bypass the Tomcat-JIRA config process altogether by downloading the Standalone distribution, which comes preconfigured with the latest stable Tomcat release.

Tomcat can be downloaded the Apache site, with earlier versions available from the archives.

On this page:

1. Unpack JIRA

Download and unzip JIRA (but not with XP's unzipper nor the default tar utility on Solaris). Ensure that you download the WAR/EAR version, not the Standalone version that is recommended on the Downloads page.

Avoid the Windows XP built-in unzip tool! The built-in unzip tool in Windows XP is broken — it silently fails to extract files with long names (see JRA-2153 ). Other users have also reported problems using WinRAR. Please use another tool like WinZIP to unpack JIRA.
Avoid the Solaris default tar utility! On Solaris, please use GNU tar to unpack JIRA in order to handle long filenames. Do not use the Solaris default tar utility.

A new directory containing JIRA will be created, hereafter referred to as $JIRA_INSTALL.

If you are using Linux/UNIX: A dedicated user should be created to run JIRA, as JIRA runs as the user it is invoked under and therefore can potentially be abused. Here is an example of how to create a dedicated user to run JIRA in Linux:
$ sudo /usr/sbin/useradd --create-home --home-dir /usr/local/jira --shell /bin/bash jira

2. Configure JIRA

2.1 Configure the 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:

          <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>

Possible values include cloudscape, db2, firebird, hsql, mckoidb, mysql, mssql, oracle, postgres, postgres72, sapdb, and sybase.

Also in entityengine.xml , locate the section:

<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>

and change this to:

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

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

2.2 Set JIRA Home

To specify the location of your JIRA Home Directory (note that you need to do this before you build JIRA):

You can specify any location on a disk for your JIRA home directory. Please be sure to specify an absolute path.

Please note that you cannot use the same JIRA home directory for multiple instances of JIRA. We recommend that you do not specify your JIRA home directory inside your installation directory, to prevent information from being accidentally lost during major operations (e.g. backing up and restoring instances).


3. Build 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 directory.

You may want to move the created WAR file to another directory. If you copy it to the Tomcat webapps/ directory, be sure that you set docBase correctly, or JIRA could be deployed twice.

4. Update Tomcat Libraries

JIRA relies on the servlet container to provide a database connection factory (javax.sql.DataSource) and Transaction Manager (javax.transaction.UserTransaction). Tomcat does not provide a transaction-aware DataSource by default, so libraries providing this capability must be added. To do this, download this package containing required extra jars (1.1M), and copy the contained jars to Tomcat's common/lib/ directory. In addition, download the commons-logging jar and copy it to common/lib/.

5. Configure Tomcat

A JIRA 'context' now needs to be set up in Tomcat. The simplest way is to copy the contents of dist-tomcat/tomcat-4/jira.xml from the built JIRA distribution, and paste it into your conf/server.xml file, inside the <Host> tag:

<Context path="/jira" docBase="path/to/atlassian-jira-3.6.war" debug="0">
  <Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"/>
  <ResourceParams name="jdbc/JiraDS">
    <parameter>
      <name>driverClassName</name>
      <value>org.hsqldb.jdbcDriver</value>
    </parameter>
    <parameter>
      <name>url</name>
      <value>jdbc:hsqldb:path/to/jira_database</value>
    </parameter>
    <parameter>
      <name>username</name>
      <value>sa</value>
    </parameter>
    <parameter>
      <name>password</name>
      <value></value>
    </parameter>

    <!-- NOTE: If not using hsqldb, comment next two parameters out -->
    <!-- Give unused connections 4 secs before eviction. -->
    <parameter>
      <name>minEvictableIdleTimeMillis</name>
      <value>4000</value>
    </parameter>
    <!-- Check for evictions every 5 secs. -->
    <parameter>
      <name>timeBetweenEvictionRunsMillis</name>
      <value>5000</value>
    </parameter>
    <parameter>
      <name>factory</name>
      <value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
    </parameter>
  </ResourceParams>

  <Resource name="UserTransaction" auth="Container" type="javax.transaction.UserTransaction"/>
  <ResourceParams name="UserTransaction">
    <parameter>
      <name>factory</name>
      <value>org.objectweb.jotm.UserTransactionFactory</value>
    </parameter>
    <parameter>
      <name>jotm.timeout</name>
      <value>60</value>
    </parameter>
  </ResourceParams>
</Context>

You need to change the paths (denoted as path/to/) to suit your installation.

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.

5.1 Configure the database connection

The example context shown above uses the HSQL database. To use a different database, copy its JDBC driver jar to common/lib/, and change the context XML appropriately (see the database doc).

6. Set mail.mime.decodeparameters

The following system property must be set in order for the JIRA mail handler to work correctly with emails from RFC 2231-compliant mail clients:

mail.mime.decodeparameters=true

System properties are set in different ways depending on your application server.

7. Start Tomcat

JIRA should now be deployed 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.

Further information

For further details, see JOTM's Tomcat HOWTO and Tomcat's documentation. If you have problems, please consult the FAQ, ask on the mailing list, or raise a support request.

Document generated by Confluence on Oct 06, 2009 00:31