This page last changed on Aug 04, 2009 by scott@atlassian.com.

These instructions will help you install JIRA on Caucho Resin 3.0.9 and above, a high-quality, free (GPL'ed) servlet container from Caucho Technology.

These instructions have been tested with Resin 3.0.9, 3.0.11 and 3.0.15. For Resin 2 releases, see the Resin 2 install docs. Please let us know if you have any problems on the mailing list.

On this page:

1. Install Resin

(if you don't already have Resin installed)

Download Resin from http://www.caucho.com/download/ and expand the distribution to a directory.

2. Configure Resin

2.1 Add extra Resin jars

Resin does not come with a few libraries that JIRA needs to run properly. These files have been placed in a zip file that you can download here. Unzip the jars in this file into the resin/lib directory.

2.2 Define database connection

You'll need to define a database connection (datasource) in Resin for JIRA to use. Open conf/resin.conf and search for 'database' to locate the correct section (after '</web-app-default>'). Exactly what text to add depends on what database you use (see database configurations). Here we assume hsqldb:

    <database>
      <jndi-name>jdbc/JiraDS</jndi-name>
      <driver>
        <type>org.hsqldb.jdbcDriver</type>
        <url>jdbc:hsqldb:/tmp/jiradb</url>
        <user>sa</user>
        <password></password>
      </driver>
    </database>

Ensure the database driver jar file is in the lib/ directory. The hsqldb jar file (containing org.hsqldb.jdbcDriver used in the example above) should already be present. Other database notes and driver details are listed here.

2.3 Resin 3.0.9 bugs

Ignore this section if you are running Resin 3.0.11 or above

Resin 3.0.9 has a bug (fixed in 3.0.11) that prevents JIRA CSS stylesheets being used. To work around this, add the following to conf/app-default.xml, below the similar 'resin-jsp' definition:

 <servlet servlet-name="jsp"
           servlet-class="com.caucho.jsp.JspServlet">
    <load-on-startup/>
  </servlet>
        

Another Resin 3.0.9 bug causes the logout page to be untranslated. This is fixed in Resin 3.0.11, or see the workaround on JRA-2685.

3. Install 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

4. Configure JIRA

Open the edit-webapp/WEB-INF/classes/entityengine.xml file, and make the changes described in the sections below.

4.1 Modify transaction factory attribute

Make the following changes (in bold) to the <transaction-factory> tag:

<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/TransactionManager" />
</transaction-factory>

4.2 Modify datasource attributes

Lower down in entityengine.xml, check that the field-type-name attribute specifies the correct type of database in use, and that the JNDI name (jdbc/JiraDS) is the same as that specified in the database definition, e.g.

   <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"
      check-indices-on-start="true">
      <jndi-jdbc jndi-server-name="default" jndi-name="java:comp/env/jdbc/JiraDS"/>
    </datasource>


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

6. Build JIRA

Now build JIRA by typing build (Windows) or ./build.sh (Unix) on the command-line. This will produce the web application to deploy in the dist-generic directory.

7. Deploy JIRA in Resin

You can add the JIRA WAR to resin/resin.conf manually, or just copy it to the resin/webapps directory.

Placing the WAR in the resin/webapps directory should cause Resin to deploy it automatically when Resin starts.

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

9. Start Resin

Start Resin as follows:

export JAVA_ARGS="-Djavax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl -Djavax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl"
cd bin
./httpd.sh

Setting JAVA_ARGS avoids a bug in Resin's built-in XML parser which breaks JIRA data imports.

JIRA should now be accessible at http://localhost:8080/(insert name of your WAR file). Follow the Setup Wizard.

Troubleshooting

If certain pages break with errors like this:

        Note: sun.tools.javac.Main has been deprecated.
        /jira/secure/views/browser/browseproject.jsp:34: Variable pageContext may
        not have been initialized.
        pageContext.write(_jsp_string4, 0, _jsp_string4.length);
        ^
      

The solution is to change Resin's compiler from 'internal' to 'javac'. See this Resin FAQ for more background.

User-contributed notes

Have experiences to share with Resin and JIRA? We welcome your thoughts. Please see the user-contributed Resin notes.


jira-jars-resin.zip (application/zip)
Document generated by Confluence on Oct 06, 2009 00:31