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

These instructions will help you install JIRA on IBM Websphere 5, noting some deviations from the generic install instructions. Please let us know if you need help, or would like to report your experiences.

JIRA works on:

  • Websphere 5.0
  • Patched versions of Websphere 5.0.1, 5.0.2 and 5.0.3 (for instance, 5.0.2.3). The unpatched releases all suffer from a Websphere bug described in JRA-2510, resulting in a blank screen when JIRA is deployed.
  • Later 5.0.x versions (one presumes)
  • Websphere 5.1 (a separate installation guide).
Warning
IBM has dropped support for Websphere 5.0 as of September 2006. Websphere 5.0 is bundled with JDK 1.3, whereas. JIRA 3.7+ requires JDK 1.4+, so you would have to upgrade JDKs to get it to work. Websphere 5.0 should thus be considered unsupported by Atlassian. We recommend users upgrade to 5.1 or above when possible.

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 Modify ear-application.xml

In the unpacked JIRA WAR distribution, edit etc/ear-application.xml, and replace:

<web>
  <web-uri>atlassian-jira-web.war</web-uri>
  <context-root>/jira</context-root>
</web>

With:

<web>
  <web-uri>atlassian-jira-web.war</web-uri>
  <context-root>jira</context-root>
</web>

The / for the context root has been removed as Websphere apparently has problems recognising this.

2.2 Modify web.xml

Copy webapp/WEB-INF/web.xml to edit-webapp/WEB-INF/web.xml, and add the following section at the end, just before the closing </web-app> tag:

<!-- resource references -->
<resource-ref>
  <description>Database for JIRA</description>
  <res-ref-name>jdbc/JiraDS</res-ref-name>
  <res-type>javax.sql.DataSource</res-type>
  <res-auth>SERVLET</res-auth>
</resource-ref>

This defines a data source for the JIRA database. This datasource is bound to a concrete JNDI name in the application deployment phase.

2.3 Configure entityengine.xml

Now edit-webapp/WEB-INF/classes/entityengine.xml may need to be modified to specify the type of database you will connect to. Here is a snippet of entityengine.xml. You may need to modify in the field-type-name.

<datasource name="defaultDS" field-type-name="hsql"
        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>

The jndi-jdbc/jndi-name attribute maps to the resource-ref/res-ref-name element defined in web.xml.

Warning
Make sure that your entityengine.xml is well-formed XML. Websphere "swallows" the error messages you should get in your log file if entityengine.xml is not well-formed, and instead reports a spurious error message.

You can test that your entityengine.xml is well-formed by opening it in Internet Explorer or Firefox. These browsers will display an error if the file is not well-formed XML, and will indicate the location of the error in the file.

2.4 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 ear' ('./build.sh ear' on Unix) on the command line. This will produce the deployable EAR file in the dist-generic/ directory.

4. Configure the Websphere datasource

The data source for the database should now be configured in Websphere, and mapped to the jdbc/JiraDS JNDI key.

5. Deploy JIRA in Websphere

The JIRA EAR file can now be deployed to Websphere.

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 JIRA

When you access the path at which you have deployed JIRA, via your web browser, theSetup Wizardshould appear.

User-contributed notes

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

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