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
You may need to click the 'Show All' link on the download page to reveal the WAR distribution.
The extracted directory is hereafter referred to as your JIRA Installation Directory.
- 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:
- 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.
- Typing the following at the Windows command line:
- (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).
- Create the dedicated user account by either:
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!
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 inedit-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
.
If you define an UNC path in Microsoft Windows, be sure to double escape the leading backslash:\\\\machinename\\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 yourJIRA_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.
- Enter the following command at a shell/console prompt (with your own JIRA Home path) before running JIRA:
- On Windows, do one of the following:
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).
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:
- 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.
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.
- Tomcat 6 JARs: http://www.atlassian.com/software/jira/downloads/binary/jira-jars-tomcat-distribution-6.4-m12-tomcat-6x.zip
- Tomcat 7 JARs:
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 thewebapp/WEB-INF/lib
subdirectory of the JIRA Installation Directory. If any of the following files are present in thewebapp/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.
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"/>
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 totrue
.
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 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:
- Right-click Tomcat's system tray icon and select 'Configure' from the resulting popup menu, which opens the 'Apache Tomcat 6 Properties' dialog box:
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=trueInitial 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/jiraYou 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 yourentityengine.xml
changes were not picked up? If so, delete thewebapps/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 thelib
subdirectory of Tomcat's installation directory. - Is the path to your built
.war
file withinserver.xml
of your Tomcat installation directory correct? (Refer to step 5 above.) - Have you copied your built
.war
file to Tomcat'swebapps
directory? This is almost guaranteed to cause problems - please move this.war
file elsewhere and delete any JIRA subdirectories created in Tomcat'swebapps
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 theconf/server.xml
file of your Tomcat installation directory? Although this is fine, be sure that you do not also have details in theserver.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'slogs
directory. On Linux/Solaris, logs will appear in a log file inlogs
, usuallylogs/*
(not justlogs/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 thesetenv.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 thebuild.sh
/build.bat
script, will construct deployable web application archive (.war
) files (for supported application servers). Thebuild.xml
file copies the contents of thewebapp
subdirectory of your JIRA Installation Directory and overwrites it with the contents of the siblingedit-webapp
directory, when constructing its.war
files. Thus, unless otherwise requested, never edit files within thiswebapp
directory!
If a file needs editing, first copy it fromwebapp/path/to/file
toedit-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.