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
| 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:
- 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 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.xmlfile (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 Set JIRA Home
- Use the JIRA Configuration Tool to change the location of your JIRA Home Directory.
The JIRA Configuration Tool is not available in JIRA WAR distributions. - Edit the
jira-application.propertiesfile 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_HOMEin 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_HOMEenvironment variable value using this format, where:Xis 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:
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).
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.0-rc2-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
.jarlibrary files before copying over new ones. To prevent exceptions related to logging, please ensure that the following files are present in Tomcat's
libdirectory. Also ensure that these files are not present in thewebapp/jira/WEB-INF/libsubdirectory of the JIRA Installation Directory. If any of the following files are present in thewebapp/jira/WEB-INF/libsubdirectory, remove them and rebuild the deployable JIRA WAR file as described in the previous step (above).File jcl-over-slf4j-x.y.z.jarjul-to-slf4j-x.y.z.jarlog4j-x.y.z.jarslf4j-api-x.y.z.jarslf4j-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:
- Copy the
jira.xmlfile from thedist-tomcat/tomcat-5.5subdirectory of your JIRA Installation Directory to theconf/Catalina/localhostsubdirectory of your Tomcat installation directory. If necessary, customise the copied
jira.xmlfile within your Tomcat installation — in particular, the value of thedocBaseattribute of theContextelement:<Context path="/jira" docBase="path/to/atlassian-jira-4.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
OutOfMemoryErrorerrors 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
OutOfMemoryerrors 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.decodeparametersstartup 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.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
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.xmlin your JIRA Installation Directory (step 2 above) and re-run the build script (step 3 above), but yourentityengine.xmlchanges were not picked up? If so, delete thewebapps/jirasubdirectory 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
libsubdirectory 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.jarpresent in thelibsubdirectory of Tomcat's installation directory. - Is the path to your built
.warfile withinconf/Catalina/localhost/jira.xmlof your Tomcat installation directory correct? (Refer to step 5 above.) - Have you copied your built
.warfile to Tomcat'swebappsdirectory? This is almost guaranteed to cause problems - please move this.warfile elsewhere and delete any JIRA subdirectories created in Tomcat'swebappsdirectory 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.xmlfile instead of theconf/Catalina/localhost/jira.xmlfile of your Tomcat installation directory? Although this is fine, be sure that you do not also have aconf/Catalina/localhost/jira.xmlfile 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'slogsdirectory. 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=truein thesetenv.sh/setenv.batfile. 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.xmlfile is an Ant file, which when invoked with thebuild.sh/build.batscript, will construct deployable web application archive (.war) files (for supported application servers). Thebuild.xmlfile copies the contents of thewebappsubdirectory of your JIRA Installation Directory and overwrites it with the contents of the siblingedit-webappdirectory, when constructing its.warfiles. Thus, unless otherwise requested, never edit files within thiswebappdirectory!
If a file needs editing, first copy it fromwebapp/path/to/filetoedit-webapp/path/to/filesubdirectories 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.