Installing JIRA on Tomcat 5.5

This guide describes how to install JIRA WAR on Tomcat 5.5, a popular open-source server from the Apache project. Tomcat can be downloaded from the Apache site.

JIRA installations which have been installed using the 'Windows Installer', 'Linux Installer' or from an 'Archive File' are pre-configured to use their own dedicated Tomcat application server. To install JIRA using one of these distributions, follow the Installing JIRA guide instead of the instructions below.

Before you begin

• Please use Tomcat 5.5.15 or later.
• Deploying multiple Atlassian applications in a single Tomcat container is not supported. We do not test this configuration and upgrading any of the applications (even for point releases) is likely to break it. There are also a number of known issues with this configuration (see this FAQ for more information).

  There are also a number of practical reasons why we do not support deploying multiple Atlassian applications in a single Tomcat container. Firstly, you must shut down Tomcat to upgrade any application and secondly, if one application crashes, the other applications running in that Tomcat container will be inaccessible.

  Finally, we recommend not deploying any other applications in the same Tomcat container that runs JIRA, especially if these other applications have large memory requirements or require additional libraries in Tomcat's lib subdirectory.

On this page:

1. Download and extract the JIRA archive

Download the JIRA WAR distribution archive from the JIRA Download page and extract its contents using a tool such as 7-zip for Windows or Linux's unzip or GNU tar tools.
You may need to click the 'Show All' link on the download page to reveal the WAR distribution.

Avoid using Windows' built-in file extraction tool! This tool silently fails to extract files with long names (see JRA-2153). Other users have also reported problems with WinRAR.

Avoid using Solaris' default tar utility! Please use GNU tar on this operating system to extract JIRA, as GNU tar handles long filenames better.

The extracted directory is hereafter referred to as your JIRA Installation Directory.

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. For example:

• If your operating system is *nix-based (for example, Linux or Solaris), type the following in a console:
  $ sudo /usr/sbin/useradd --create-home --comment "Account for running JIRA" --shell /bin/bash jira

• If your operating system is Windows:
  1. Create the dedicated user account by either:
     • Typing the following at the Windows command line:
       > net user jira mypassword /add /comment:"Account for running JIRA"
       (This creates a user account with user name 'jira' and password 'mypassword'. You should choose your own password.)
     • Opening the Windows 'Computer Management' console to add your 'jira' user with its own password.
  2. (Optional) Use the Windows 'Computer Management' console to remove the 'jira' user's membership of all unnecessary Windows groups, such as the default 'Users' group.
     If Windows is operating under a Microsoft Active Directory, ask your Active Directory administrator to create your 'jira' account (with no prior privileges).

To maximise security, ensure that this user can only write to the logs, temp and work directories of your application server (Apache Tomcat) installation and your JIRA Home Directory.

2. Configure JIRA

2.1 Customising your JIRA installation directory files

(This section is optional and recommended for experts only.)

2.1.1 How to customise files in your JIRA installation directory

If you wish to customise any files in the <jira-application-dir> (i.e. the webapp subdirectory) of your JIRA Installation Directory, please perform them in the sibling edit-webapp subdirectory only.

To edit a file within the webapp subdirectory, first copy it from the webapp/path/to/file subdirectory to the edit-webapp/path/to/file subdirectory of your JIRA Installation Directory and edit it in the latter location.

When building JIRA (below), .war files are constructed based on file contents copied from the webapp subdirectory of your JIRA Installation Directory, which are overwritten by file contents from the sibling edit-webapp directory. Thus, never edit files within this webapp directory!

Be aware that the more files you customise in your JIRA Installation Directory, the more difficult it will be to upgrade JIRA or migrate JIRA to another server, as your customisations will need to be migrated manually over to your new JIRA installation.

2.1.2 Configuring the entityengine.xml file

Ensure that the Transaction Factory has been specified correctly in JIRA's entityengine.xml file. For more information, see Configuring the Entity Engine for JIRA.

• In the entityengine.xml file (located in edit-webapp/WEB-INF/classes/ of the JIRA Installation Directory), ensure the <transaction-factory>...</transaction-factory> tag contains:

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

  See Configuring the Entity Engine for JIRA for more information about configuring JIRA's database access layer.

2.2 Set JIRA Home

• Edit the jira-application.properties file and set the value of the 'jira.home' property to the desired location for your JIRA Home Directory. If you are specifying this location's path on Windows, use double back-slashes ("\") between subdirectories. For example, X:\\path\\to\\JIRA\‌\Home
  See the JIRA Installation Directory page to find where this file is located.
• Set an environment variable named JIRA_HOME in your operating system whose value is the location of your JIRA Home Directory. To do this:

  • On Windows, do one of the following:
    
    • Configure this environment variable through the Windows user interface (typically through 'My Computer' or 'Computer')
    • At the command prompt, enter the following command (with your own JIRA Home path) before running JIRA from the command prompt:
      
      • set JIRA_HOME=X:\path\to\JIRA\Home
        Please set your JIRA_HOME  environment variable value using this format, where:
        
        • X is the drive letter where your JIRA Home Directory is located and
        • no spacing has been added around the equal sign ('=')
    • Specify the command above in a batch file used to start JIRA.
  • On Linux/Solaris, do one of the following:
    
    • Enter the following command at a shell/console prompt (with your own JIRA Home path) before running JIRA:
      
      • export JIRA_HOME=/path/to/jira/home
    • Specify the command above in a script used to start JIRA.

For more information about setting up your JIRA Home Directory, please see Setting your JIRA Home Directory.

3. Build JIRA

Now build JIRA by running build.bat (Windows) or ./build.sh (Linux/Solaris) on the command line in the JIRA Installation Directory. This will produce the deployable WAR file in the dist-tomcat subdirectory of the JIRA Installation Directory.

4. Update your Tomcat installation's libraries for JIRA

4.1 JDBC drivers

Your Tomcat installation requires an appropriate JDBC driver to allow JIRA to communicate with the database. To add this JDBC driver to Tomcat, refer to the appropriate instructions:

• Copy the PostgreSQL JDBC Driver to Tomcat
• Copy the MySQL JDBC Driver to Tomcat
• Copy the Oracle JDBC Driver to Tomcat
• Copy the SQL Server 2005 JDBC Driver to Tomcat
• Copy the SQL Server 2008 JDBC Driver to Tomcat
• Copy the HSQL JDBC Driver to Tomcat
  If you intend to use the HSQL database, the HSQL JDBC driver is already included with the other JIRA library files that will be added to Tomcat in the following step.

4.2 Other JIRA libraries for Tomcat

Tomcat does not come with some libraries required to run JIRA. To fix this, download http://www.atlassian.com/software/jira/downloads/binary/jira-jars-tomcat-distribution-5.1-tomcat-5x.zip extract and copy the .jar library files from this archive to the common/lib subdirectory of your Tomcat installation directory.

Please Note:

• Be sure to remove existing versions of these .jar library files before copying over new ones.

• To prevent exceptions related to logging, please ensure that the following files are present in Tomcat's lib directory. Also ensure that these files are not present in the webapp/jira/WEB-INF/lib subdirectory of the JIRA Installation Directory. If any of the following files are present in the webapp/jira/WEB-INF/lib subdirectory, remove them and rebuild the deployable JIRA WAR file as described in the previous step (above).

  File
  jcl-over-slf4j-x.y.z.jar
  jul-to-slf4j-x.y.z.jar
  log4j-x.y.z.jar
  slf4j-api-x.y.z.jar
  slf4j-log4j12-x-y-z.jar

5. Configure JIRA's context in Tomcat

A JIRA 'context' now needs to be set up in Tomcat. To do this:

1. Copy the jira.xml file from the etc subdirectory of your JIRA Installation Directory to the conf/Catalina/localhost subdirectory of your Tomcat installation directory.

2. If necessary, customise the copied jira.xml file within your Tomcat installation — in particular, the value of the docBase attribute of the Contextelement:

   <Context path="/jira" docBase="path/to/atlassian-jira-5.x.war" debug="0" useHttpOnly="true">
   
     <Resource name="UserTransaction" auth="Container" type="javax.transaction.UserTransaction"
       factory="org.objectweb.jotm.UserTransactionFactory" jotm.timeout="60"/>
     <Manager pathname=""/>
   
   </Context>
   

The paths (denoted as path/to/) will be correct by default, assuming you want to deploy the .war from the dist-tomcat subdirectory of your JIRA Installation Directory.

If you are installing in Windows, make sure that the paths you specify for the location of the WAR file and database are full paths with drive letters (e.g. C:\path\to\atlassian-jira-4.x.war).

6. Modify Tomcat's server.xml to handle internationalised characters correctly

In order for JIRA to correctly display internationalised characters in user and group names, you need to modify the conf/server.xml file in your Tomcat installation directory by specifying the URIEncoding="UTF-8" property within the connector definition for your HTTP protocol.

The connector definition is specified by the following element in your server.xml file:

<Connector port="8080" maxHttpHeaderSize="8192"
    maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
    enableLookups="false" redirectPort="8443" acceptCount="100"
    connectionTimeout="20000" disableUploadTimeout="true"/>

You should modify this element by specifying the URIEncoding="UTF-8" attribute:

<Connector port="8080" maxHttpHeaderSize="8192"
    maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
    enableLookups="false" redirectPort="8443" acceptCount="100"
    connectionTimeout="20000" disableUploadTimeout="true" URIEncoding="UTF-8"/>

Please Note:

• Since this property must be specified at the connector level for your application server, this setting will effect all other web applications deployed to the same application server installation running JIRA. While this setting should not adversely effect these other web applications, you should be aware of this point.
• JIRA will run fine without this property set. However, you will run into issues if a user or group is created which contains international characters. Hence, it is recommended that you set this property.

7. Fix memory and mail handling settings in Tomcat

Memory and mail handling settings need to be modified in Tomcat to avoid the following issues:

• Tomcat effectively leaks memory by caching JSPs. This can result in OutOfMemoryError errors if large pages (such as RSS or Excel pages) are requested.
• JIRA requires more memory than what Tomcat provides by default. This may lead to OutOfMemory errors when running JIRA if these memory settings are not increased.
• For JIRA's mail handler to avoid problems with RFC 2231-compliant mail clients, set the mail.mime.decodeparameters startup parameter in Tomcat to true.

To prevent these issues, follow the appropriate instructions for your operating system below.

For Windows

If Tomcat is not installed as a service:

• Edit Tomcat's bin/setenv.batfile (or create this file if it does not exist) and set:

  set CATALINA_OPTS=%CATALINA_OPTS% -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true -Dmail.mime.decodeparameters=true -Xms128m -Xmx512m -XX:MaxPermSize=256m
  

If you wish to run Tomcat as a service:

• Run the following command from Windows command prompt:

  tomcat5 //US//JIRA ++JvmOptions="-Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true -Dmail.mime.decodeparameters=true -Xms128m -Xmx512m -XX:MaxPermSize=256m"
  

For Linux/Solaris

Edit Tomcat's bin/setenv.sh file (or create this file if it does not exist) and set:

export CATALINA_OPTS="$CATALINA_OPTS -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true -Dmail.mime.decodeparameters=true -Xms128m -Xmx512m -XX:MaxPermSize=256m"

For other environments and more information on memory settings, see Increasing JIRA Memory.

8. Start Tomcat

(Only required if Tomcat is not running as a service.)

JIRA should now be ready to run in Tomcat. To start up JIRA, start (or restart) the Tomcat server with Tomcat's bin/startup.sh or bin/startup.bat scripts.

9. Run the setup wizard

Point your browser to

You should now see the Setup Wizard, which will take you through the JIRA's setup procedure, including a configuration step for your database connection.

Troubleshooting

It is easy to make a mistake in this process. First, check that you have followed the process described above:

• Have you have made changes to edit-webapp/WEB-INF/classes/entityengine.xml in your JIRA Installation Directory (step 2 above) and re-run the build script (step 3 above), but your entityengine.xml changes were not picked up? If so, delete the webapps/jira subdirectory of your Tomcat installation directory and then restart JIRA. (In some circumstances, Tomcat does not correctly re-expand the web application.)
• If you are using an external database, did you copy the correct JDBC driver jar file to the lib subdirectory of your Tomcat installation directory? (Refer to step 4 above.)
• Have you updated your Tomcat installation's libraries for JIRA by copying across the additional jar files downloaded in step 4 above? Check if objectweb-datasource-x.y.z.jar present in the lib subdirectory of Tomcat's installation directory.
• Is the path to your built .war file within conf/Catalina/localhost/jira.xml of your Tomcat installation directory correct? (Refer to step 5 above.)
• Have you copied your built .war file to Tomcat's webapps directory? This is almost guaranteed to cause problems - please move this .war file elsewhere and delete any JIRA subdirectories created in Tomcat's webapps directory which Tomcat may have created (after Tomcat is initially started).
• Have you configured JIRA's context and other custom settings centrally in Tomcat's conf/server.xml file instead of the conf/Catalina/localhost/jira.xml file of your Tomcat installation directory? Although this is fine, be sure that you do not also have a conf/Catalina/localhost/jira.xml file present.
• The log files are usually vital to debugging problems. On Windows, these will appear in the console window that loads when running startup.bat, or in one of the log files in Tomcat's logs directory. On Linux/Solaris, logs will appear in a log file in logs, usually logs/* (not just logs/catalina.out). Check the log file for errors after startup.
• If you experience high memory usage / memory leaks (e.g. OutOfMemoryError), you may wish to set the system property -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true in the setenv.sh / setenv.bat file. For more information please see JRA-10145. (Refer to step 7 above.)
• If the connection to your database is dropping out (in particular with MySQL), you will need to set up Tomcat to survive connection closures.
• Please be aware: The build.xml file is an Ant file, which when invoked with the build.sh / build.bat script, will construct deployable web application archive (.war) files (for supported application servers). The build.xml file copies the contents of the webapp subdirectory of your JIRA Installation Directory and overwrites it with the contents of the sibling edit-webapp directory, when constructing its .war files. Thus, unless otherwise requested, never edit files within this webapp directory!
  If a file needs editing, first copy it from webapp/path/to/file to edit-webapp/path/to/file subdirectories of your JIRA Installation Directory and edit it in the latter location.

If you are stuck, then please consider installing one of the 'recommended' distributions of JIRA.

User-contributed notes

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