Installing JIRA on Tomcat 4.0.x

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.

1. Unpack JIRA

Unzip the JIRA WAR (Webapp ARchive) distribution. A new directory containing JIRA will be created, hereafter referred to as $JIRA_HOME

2. Configure JIRA

JIRA needs to be told what type of database you'll be using. The database is specified in $JIRA_HOME/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.

3. Build JIRA

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

Warning

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.

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

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.

For further details..

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.