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

Skip to end of metadata
Go to start of metadata

This Installation Guide applies if you are installing JIRA for the first time. If you are upgrading JIRA, please refer to the Upgrade Guide.

Which 'Distribution' Should You Choose?

JIRA is available in two 'distributions':

Standalone distribution

WAR/EAR distribution

Pre-packaged with Tomcat application server

Deploys into an existing application server

Pre-packaged with HSQLDB database, but can be easily connected to any supported database

Connects to any supported database

Requires virtually no setup

Requires manual configuration

Recommended for all users

Suitable only for system administrators

The Standalone distribution is recommended, even for organisations with an existing application server environment. Please note however, that the HSQLDB database pre-packaged with the Standalone distribution is suitable for evaluation purposes only.

Installing JIRA WAR/EAR

The distribution ZIP file contains an Ant build script to create a deployable EAR or WAR for your particular application server (and any necessary library directories).

The basic set of steps to install JIRA WAR/EAR is as follows:

  1. Download and unzip JIRA (but not with XP's unzipper nor the default tar utility on Solaris). Ensure that you download the WAR/EAR version, not the Standalone version that is recommended on the Downloads page.
    Avoid the Windows XP built-in unzip tool! The built-in unzip tool in Windows XP is broken — it silently fails to extract files with long names (see JRA-2153 ). Other users have also reported problems using WinRAR. Please use another tool like WinZIP to unpack JIRA.
    Avoid the Solaris default tar utility! On Solaris, please use GNU tar to unpack JIRA in order to handle long filenames. Do not use the Solaris default tar utility.

    A new directory containing JIRA will be created, hereafter referred to as $JIRA_INSTALL.

    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. Here is an example of how to create a dedicated user to run JIRA in Linux/UNIX:

    $ sudo /usr/sbin/useradd --create-home --home-dir /usr/local/jira --shell /bin/bash jira

    To maximise security, ensure that this user can only write to the JIRA directories (not to the entire file system).

  2. Follow the instructions in the readme.txt file, located in the root directory of the unpacked JIRA distribution. This refers to the server-specific installation guides:
  3. Set your JIRA home directory as described in Setting your JIRA Home Directory.
  4. The following system property must be set in order for the JIRA mail handler to work correctly with emails from RFC 2231-compliant mail clients:

    System properties are set in different ways depending on your application server.

  5. Access JIRA using your web browser and run through the brief Setup Wizard.
  6. For production use, please check that your application server is allocated sufficient memory. Java applications claim up to only 64Mb by default, and this usually isn't enough for JIRA. See Increasing JIRA memory for more information.


  • 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).

    We also strongly recommend that you do not deploy multiple Atlassian applications in a single Tomcat container for a number of practical reasons. Firstly, you will need to shut down Tomcat to upgrade any application and secondly, if one application crashes, the other applications running in the Tomcat container will be inaccessible.

Next Steps