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

These instructions will help you install JIRA on JBoss 3.x (with embedded Jetty or Tomcat). These instructions have been tested with JBoss 3.2.3. Earlier releases are not expected to work fully (see JRA-4977, JRA-3667).


There is also separate guide for installing JIRA on JBoss 2.4, but we recommend using JBoss 3.x rather than JBoss 2.4 if you can (though if you have a choice, prefer Tomcat — it is significantly faster).

If you're having problems, see debugging JIRA.

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 JBoss

The application server (JBoss) is responsible for establishing a database connection, and making it available to webapps like JIRA as a "DataSource". JBoss comes with one DataSource preconfigured using a built-in hsqldb database. You can see the configuration for this in server/default/deploy/hsqldb-ds.xml. In the rest of this guide, we assume use of this DataSource (called 'DefaultDS').

If you wish to use another database (MySQL, Oracle etc), create another config file in the 'deploy' directory, e.g. server/default/deploy/jira-ds.xml:

<?xml version="1.0" encoding="UTF-8"?>
<!-- DataSource for JIRA webapp,
     called 'JiraDS' (must be same in entityengine.xml) -->
<datasources>
  <local-tx-datasource>
    <jndi-name>JiraDS</jndi-name>
    <connection-url>jdbc:mysql://localhost/jiradb?autoReconnect=true</connection-url>
    <driver-class>com.mysql.jdbc.Driver</driver-class>
    <user-name>jira_mysql_username</user-name>
    <password>jira_mysql_password</password>
  </local-tx-datasource>
</datasources>

Here we have created a MySQL DataSource called 'JiraDS'. We would also have to copy the MySQL JDBC jar to servers/default/lib/. See the database configuration page for details.

3. Configure JIRA

Open the edit-webapp/WEB-INF/classes/entityengine.xml file, and make the following changes:

3.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="UserTransaction" />
  <transaction-manager-jndi jndi-server-name="default"
    jndi-name="java:/TransactionManager" />
</transaction-factory>

3.2 Modify datasource attributes

Lower down in entityengine.xml, the <datasource> tag needs modifying in two locations:

<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:/DefaultDS"/>
</datasource>

* The field-type-name parameter needs to be set appropriately for the type of database you use.

  • The jndi-name attribute needs to point to a DataSource to use. As mentioned above, JBoss comes preconfigured with a "DefaultDS" DataSource, which we assume use of here. If instead, you added the MySQL DataSource above, the jndi-name value would be java:/JiraDS.

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

5. Build JIRA

Now build JIRA by typing build (Windows) or ./build.sh (Unix) on the command line, in the directory where you originally extracted JIRA to. This will produce a deployableWARfile in the dist-generic directory.

6. (optional) Remove old deployments

On some versions of JBoss you may need to undeploy any old JIRA EARs/WARs and remove all deployed files before deploying the new WAR.

7. Deploy the WAR in JBoss

Rename the WAR to jira.war, and drop it into your deployment directory (usually jboss/server/default/deploy/). If JBoss is running, you should see messages on the JBoss console saying that it is deploying the WAR.

The version of tomcat that ships with JBoss 3.2.x ships with an earlier version of the commons-collections.jar. JIRA requires the commons-collections-3.1.jar. You will need to replace the version shipped with the tomcat instance in JBoss (usually found in {JBOSS_HOME}/server/default/deploy/jbossweb-tomcat50.sar/commons-collections.jar) with the version shipped with JIRA (usually found in {JIRA_HOME}/WEB-INF/lib/commons-collections-3.1.jar).

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 JBOSS

Start JBOSS by running bin/run.bat under the JBoss directory. Watch the startup logs for errors. Once JBoss has started, JIRA should be accessible at http://localhost:8080/jira/ (change the host and port as needed; the 'jira' part is whatever the WAR name is).

User-contributed notes

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

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