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

If you have configured JIRA on an app server not documented by Atlassian, please share your experiences with others.

JIRA should be able to work on any J2EE 1.3 compliant application server or Servlet 2.3 compliant web container.

The main installation issues are always to do with getting the right files in the right place for the server so the classpaths are all working correctly, and finding the JNDI locations of various objects.

We'll now go through the general steps required to install JIRA from the WAR (Webapp ARchive) distribution.

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 Database Connection

As described above, we need to edit entityengine.xml to tell JIRA about its database and transaction manager. Edits should be made to edit-webapp/WEB-INF/classes/entityengine.xml .

You will need to know the JNDI locations of:

  • the javax.transaction.UserTransaction and javax.transaction.TransactionManager objects, for the transaction manager
  • the location of your datasource (if configured via the server).

For more information on how to configure the entityengine.xml please see Configuring the Entity Engine for JIRA.

2.2 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

JIRA can now be built by typing build (Windows) or ./build.sh (Unix) on the command line in the $JIRA_INSTALL directory. This will produce the deployable WAR file in the $JIRA_INSTALL/dist-* directories.

4. Deploy JIRA

Deploy the JIRA EAR or WAR in your application server — consult your server's specific documentation for how to do this.

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

6. Bind the JIRA website

JIRA has a single web module called atlassian-jira-web (for later versions, the module name is the same as the name of the WAR or EAR file that is generated from the ant process). You may need to configure this as a web module within your server.

7. Start JIRA

When you access the path at which you have deployed JIRA, via your web browser, the Setup Wizard should appear.

Next steps

  • For production use, please check that your application server is allocated sufficient memory. Java applications claim up to only 64Mb by default, and this usually isn't enough for JIRA. See Increasing JIRA Memory for more information.

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