Installing JIRA on Tomcat 6.0 or 7.0

This guide describes how to install the JIRA WAR distribution on Tomcat 6.0 or Tomcat 7.0, 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 recommended distributions, follow the Installing JIRA guide instead of the instructions below.

Before you begin

Please read the following important notes before you begin installing JIRA on Tomcat 6.0/7.0:

  • Tomcat 6.0.24 contains a critical bug. Please use 6.0.32 instead.
  • 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.
(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) On Solaris, use GNU tar to extract JIRA instead of the Solaris' default tar utility 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 Customizing your JIRA installation directory files

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

2.1.1 How to customize files in your JIRA installation directory

If you wish to customize 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 customize in your JIRA Installation Directory, the more difficult it will be to upgrade JIRA or migrate JIRA to another server, as your customizations 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 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 (this location should be something different than the application directory, or you may run into problems later). If you are specifying this location's path on Windows, use double back-slashes ("\") between subdirectories. For example, X:\\path\\to\\JIRA\‌\Home.
    (info)If you define an UNC path in Microsoft Windows, be sure to double escape the leading backslash: \\\\machinename\\path\\to\\JIRA\\home
    (info) 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
          (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 minimize 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. Update your Tomcat installation's libraries for JIRA

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

3.2 Other JIRA libraries for Tomcat

Tomcat does not come with some libraries required to run JIRA. To fix this, download the relevant archive depending on your Tomcat version (see below), extract and copy the .jar library files from this archive to the 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/WEB-INF/lib subdirectory of the JIRA Installation Directory. If any of the following files are present in the webapp/WEB-INF/lib subdirectory of the JIRA Installation Directory, remove them before building the deployable JIRA WAR file as described in the next step.

    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

4. 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/tomcat-6 subdirectory of the JIRA Installation Directory.

5. Configure JIRA's context in Tomcat

A JIRA 'context' now needs to be set up in Tomcat. To do this, add the below configuration to the Tomcat server.xml file. The value of docBase will need to be modified to point to the JIRA WAR file.

<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>
  • If installing JIRA 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-5.x.war).
  • If installing on Linux, ensure the path does not use any special characters.

(warning) These details can also be configured in conf/Catalina/localhost/jira.xml (you may need to create the jira.xml file if it does not exist) however they cannot be configured in both server.xml and jira.xml. If they are, it will cause significant problems with the JIRA instance.

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

In order for JIRA to correctly display internationalized 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" protocol="HTTP/1.1"
        connectionTimeout="20000"
        redirectPort="8443"/>

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

<Connector port="8080" protocol="HTTP/1.1"
        connectionTimeout="20000"
        redirectPort="8443" URIEncoding="UTF-8"/>

(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.batfile (or create this file if it does not exist) and add the following to this file:

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

If Tomcat is installed and running as a service:

  1. Right-click Tomcat's system tray icon and select 'Configure' from the resulting popup menu, which opens the 'Apache Tomcat 6 Properties' dialog box:
  2. In this dialog box, click on the 'Java' tab and specify the following values:

    Field

    Value

    Java Options (append to the existing value)

    -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true
    -Dmail.mime.decodeparameters=true

    Initial memory pool

    128

    Maximum memory pool

    512

    Your configuration should be similar to the screenshot below:

For Linux/Solaris

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

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

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 server.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/Catalina/localhost/jira.xml file instead of the conf/server.xml file of your Tomcat installation directory? Although this is fine, be sure that you do not also have details in the server.xml file 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, 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.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport