Installing JIRA on Tomcat 5.0

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

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"
          helper-class="org.ofbiz.core.entity.GenericHelperDAO"
          field-type-name="hsql"
          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

For Postgres 7.3+ and DB2 you also need to set a schema-name attribute (see the Postgres and DB2 pages).

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

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.

Tomcat does not come with some libraries required to run JIRA. To fix this, download jira-jars-tomcat5.zip (1.2Mb), and copy the contained jars to Tomcat's common/lib/ directory.

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

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

2. Customize the copied jira.xml as follows:

   <Context path="/jira" docBase="path/to/atlassian-jira-3.3.3.war" debug="0">
     <Logger className="org.apache.catalina.logger.FileLogger"
             prefix="atlassian-jira." suffix=".log" timestamp="true"/>
     <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, delete the next two parameters -->
       <!-- 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>
   

The paths (denoted as path/to/) will be correct by default, assuming you want to deploy the .war from the dist-tomcat/ 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:\yourdb\tomcatdb). N.B. the last part of the path is the name of the database and is not a directory.

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

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_HOME/edit-webapp/WEB-INF/classes/entityengine.xml? (step 1)
• Have you previously started JIRA with an incorrect field-type-name value? If so, the database schema would have been created incorrectly.
• Have you copied the extra Tomcat jars (step 4)? Check if you have common/lib/objectweb-datasource-1.4.3.jar present.
• If using an external database, did you copy the JDBC driver jar to common/lib/ (step 5)?
• 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 pain - 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/catalina.out. Check the log file for errors after startup.

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. If you have a general question, please contact Atlassian, or try the jira-user mailing list (which Atlassian staff monitor).