Installing JIRA on JBoss 4

These instructions will help you install JIRA on JBoss 4.

If you're having problems, see Getting Help.

JIRA 4.0 does not work with JBoss 5

JBoss 5 currently does not work with JIRA 4.0 due to an outstanding JBoss issue with the Apache Xerces. Please see this JBoss issue for further details.

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". DataSources are configured in XML files under JBoss' server/default/deploy/ directory.

2.1. Configure the datasource

For production use, you should configure JBoss to provide a datasource for an external database like PostgreSQL or MySQL. DataSources are configured in XML files under server/default/deploy/. Create a new file, server/default/deploy/jira-ds.xml containing:

<?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/jirajboss?autoReconnect=true&amp;useUnicode=true&amp;characterEncoding=UTF8</connection-url>
    <driver-class>com.mysql.jdbc.Driver</driver-class>
    <user-name>jira_mysql_username</user-name>
    <password>jira_mysql_password</password>
    <min-pool-size>5</min-pool-size>
    <max-pool-size>10</max-pool-size>
  </local-tx-datasource>
</datasources>

Here we have created a DataSource called 'JiraDS'. Change the connection-url and other details as required for your database (the database configuration guides show the correct connection-url and driver-class entry formats). Note: min-pool-size and max-pool-size are used to configure the minimum and maximum connection pool sizes respectively.

2.2. Add the JDBC driver

Download the right JDBC driver for your database (again, see the relevant database configuration guide for where to get it). Copy the driver's jar file in JBoss' servers/default/lib directory. If you are using the built-in HSQLDB database, the JDBC driver (hsqldb.jar) is already present.

3. Configure the JIRA webapp

The following steps assume that you have the JIRA WAR/Webapp distribution.

3.1. Modify transaction factory attributes

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

    <transaction-factory class="org.ofbiz.core.entity.transaction.JNDIFactory">
      <user-transaction-jndi jndi-server-name="default" jndi-name="java:comp/env/UserTransaction"/>
      <transaction-manager-jndi jndi-server-name="default" jndi-name="java:comp/env/UserTransaction"/>
    </transaction-factory>

to:

    <transaction-factory class="org.ofbiz.core.entity.transaction.JNDIFactory">
      <user-transaction-jndi jndi-server-name="default" jndi-name="ClientUserTransaction"/>
      <transaction-manager-jndi jndi-server-name="default" jndi-name="java:/TransactionManager"/>
    </transaction-factory>

For JBoss 4.0.1 and 4.0.2, use UserTransaction rather than ClientUserTransaction.

3.2. Specify database type and JNDI path

You now need to make changes to the entityengine.xml file to specify the database type and JNDI path. These changes will differ, depending on whether you are using HSQLDB or an external database (not HSQLDB). Go to the bottom of edit-webapp/WEB-INF/classes/entityengine.xml where the database type and datasource JNDI location are specified:

<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"/>

For HSQLDB (using the built-in datasource from Â§1.1) all you need to do is replace java:comp/env/jdbc/JiraDS with java:/DefaultDS

For external databases (not HSQLDB):

Change field-type-name appropriately for your database.
If necessary, adjust schema-name appropriately your database.
Replace java:comp/env/jdbc/JiraDS with 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):

Edit the jira-application.properties file (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 ("\").

Jira ホームディレクトリにはディスク上の任意の場所を指定できます。絶対パスを指定するようにします。

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

5. JIRA のビルド

Now build a JIRA webapp 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 deployable WAR file in the dist-generic directory.

6. Deploy the WAR in JBoss

Copy and rename dist-generic/atlassian-jira-*.war to server/default/deploy/jira.war in JBoss.

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

8. Start JBoss

Stop and start JBoss to fully deploy the new JIRA webapp. 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).

ユーザーから寄せられた注意点

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

Child pages