Documentation for JIRA 4.4. Documentation for other versions of JIRA is available too.

Skip to end of metadata
Go to start of metadata
Gliffy Zoom Zoom

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.

The JIRA Standalone distribution is JIRA preconfigured with a copy of Tomcat. If you have JIRA Standalone, follow the Installing JIRA Standalone 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.

1. Download and Extract the JIRA Archive

Download the JIRA WAR distribution archive from the JIRA Download Center and extract its contents using a tool such as 7-zip for Windows or Linux's unzip or GNU tar tools.
(tick) You may need to click the 'Show All' link on the download page to reveal the WAR distribution. (warning) 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. (warning) 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.
      (tick) If Windows is operating under a Microsoft Active Directory, ask your Active Directory administrator to create your 'jira' account (with no prior privileges).

(info) 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!

(warning) 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:

    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
    (info) See the JIRA Installation Directory page to find where this file is located.
  • Use the JIRA Configuration Tool (available in JIRA Standalone only) to change the location of your JIRA Home Directory.
  • 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
          (warning) 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.
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 locating your JIRA Home Directory completely independently of the JIRA Installation Directory (i.e. not nesting one within the other) as this will minimise information being lost during major operations (e.g. backing up and restoring instances).

(info) 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:

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-4.4-tomcat-5x.zip extract and copy the .jar library files from this archive to the common/lib subdirectory of your Tomcat installation directory.
(warning) Be sure to remove existing versions of these .jar library files before copying over new ones.

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 dist-tomcat/tomcat-5.5 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 Context element:

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:

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

(info) 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.bat file (or create this file if it does not exist) and set:

If you wish to run Tomcat as a service:

  • Run the following command from Windows command prompt:

For Linux/Solaris

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

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 http://localhost:8080/jira

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.
  • (warning) 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, 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're stuck, please raise a support request, and attach your logs, configuration files, plus anything else relevant, and we'll get back to you as soon as possible.

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.