These instructions will help you install JIRA on IBM Websphere 6.x.
On this page:
- 1. Unpack JIRA
- 2. Configure JIRA
- 3. Build JIRA
- 4. Configure the Websphere datasource
- 5. Deploy JIRA in Websphere
- 6. Set mail.mime.decodeparameters
- 7. Ensure Websphere compiles JSPs in Java 1.5
- 8. Start JIRA
- User-contributed notes
1. Unpack JIRADownload 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.
A new directory containing JIRA will be created, hereafter referred to as
2. Configure JIRA
2.1 Configure entityengine.xml
edit-webapp/WEB-INF/classes/entityengine.xml file needs to be modified to specify the correct database field type. The example below is configured for MS SQL Server.
- In the Transaction Factory section:
"/env"if it is there, i.e. change this: to this:
- In the Datasource section:
Please ensure that the value of the
jndi-jdbc/jndi-nameattribute has the
"java:comp/env"prefix. The prefix should be in the file by default.
2.2 Set JIRA HomeTo specify the location of your JIRA Home Directory (note that you need to do this before you build JIRA):
- Edit the
jira-application.propertiesfile (see the JIRA Installation Directory page to find where this file is located), add a 'jira.home' property and set it to your desired location for the JIRA home directory. Please use forward-slashes ("/"), not back-slashes ("\").
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 to be inside your installation directory, to prevent information from being accidentally lost during major operations (e.g. backing up and restoring instances).
2.3 Modify web.xml
webapp/WEB-INF/web.xml file and remove lines:
which appear towards the bottom of the file. After removing the lines the
<resource-ref> entry should look like:
Please ensure that the
res-sharing-scope is set to Unshareable.
3. Build JIRA
Now build JIRA by running the build script for your platform (e.g.
build.bat on Windows or
build.sh on a Unix or Linux system). This will produce the deployable WAR file in the
4. Configure the Websphere datasource
4.1 Download the datasource
4.2 Configure the datasource
Perform the following steps in the Websphere Administration Console.
4.2.1 Create a JDBC Provider
Resources -> JDBC Providers, and create a new JDBC Provider for the database you wish to deploy to.
- Set the Classpath field to include the JDBC driver jar.
- In the Implementation Classname field, you need to enter the name of a DataSource implementation classname, not the JDBC driver classname. For instance, the MySQL JDBC driver class is 'com.mysql.jdbc.Driver', but here we need to enter 'com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource'.
Consult your database documentation for details.
4.2.2 Create a DataSource
Now select your newly created JDBC Provider, and add a DataSource (the name of the DataSource doesn't matter).
The important thing to get right here is the JNDI Name. This must be the same as that specified in your webapp. For JIRA, that means it has to correspond to:
4.2.3 Configure the DataSource
In the 'Custom Properties' section, specify the username and password which JIRA will use to connect to the database, and the JDBC URL to use.
4.2.4 Test the connection
Test the connection, and if it all works, save the changes.
5. Deploy JIRA in Websphere
The JIRA WAR file can now be deployed to Websphere (by e.g. using Websphere's Administration Console). Note that you must:
- Bind JIRA's
jdbc/JiraDSdatasource to Websphere's
- Enable application-first (parent-last) classloading, the 'Classes loaded with application class loader first' and the 'Single classloader for application' WAR classloader policy.
- Use the WAR file in
dist-genericdirectory and NOT the
- Turn WebSphere's "Servlet Caching" off. Otherwise JIRA will die with ClassCastExceptions.
6. Set mail.mime.decodeparametersThe following system property must be set in order for the JIRA mail handler to work correctly with emails from RFC 2231-compliant mail clients:
Refer to Setting Properties and Options on Startup for instructions.
7. Ensure Websphere compiles JSPs in Java 1.5
To ensure that Websphere compiles JSPs in Java 1.5 successfully, you must:
- Edit the
ibm-web-ext.xmibindings file located within the
WEB-INFdirectory of your Websphere Application Server's WAR file.
The following example shows a typical location for this binding file:
- Add the following entry into this bindings file:
[number]must be a unique integer with respect to the other
<jspAttributes xmi:id="JSPAttribute_[number]"...entries in this file.
- Save the updated
For more information, please refer to the following references:
- Procedure for modifying Websphere's JSP engine parameters
- Procedure for resolving JSP compilation problems in Websphere 6.1
8. Start JIRA
When you access the path at which you have deployed JIRA, via your web browser, the Setup Wizard should appear.
Have experiences to share with Websphere 6.x and JIRA? We welcome your thoughts. Please see the user-contributed Websphere notes.