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

Skip to end of metadata
Go to start of metadata

This document describes the standard, recommended procedure for upgrading to JIRA 4.3.x from JIRA version 4.0.0 or later.

If any of the following points applies to your situation, use the migration procedure to upgrade JIRA instead:

  • You are upgrading from a version of JIRA prior to 4.0.0.
  • You are changing the location of your index and/or attachments path for JIRA 4.3.x.
  • You are changing the operating system that will run JIRA 4.3.x.
  • You are changing the database system that will store JIRA's data.

Upgrading to JIRA 4.3?

Icon


If so, please review the JIRA 4.3 Release Notes and JIRA 4.3 Upgrade Guide for important information about this version of JIRA.

On this page:

(warning) Please read/perform all steps and sub-steps in consecutive order.

1. Before You Start

  1. You will need current software maintenance  to perform the upgrade. If you are unsure, confirm the following:
  2. Read the release notes and upgrade guidefor the version of JIRA you are upgrading to. The upgrade guide (in particular) contains important information that may be relevant to your JIRA installation.
    • If you plan to skip a few JIRA versions for your next JIRA upgrade, we strongly recommend that you read the upgrade guides for all major versions between your current version and the version to which you are upgrading. Refer to Important Version-Specific Upgrade Guides for quick links to these guides.
  3. Confirm that your Java platform, operating system, application server, database and hardware still comply with the requirements for JIRA 4.3.x. Newer versions of JIRA may have different requirements and supported platforms to previous JIRA versions.
    (tick) The End of Support Announcements for JIRA page also has important information regarding platform support for future versions of JIRA.
  4. Check for any known issues in the JIRA Knowledge Base.
  5. If you have installed any additional JIRA plugins (i.e. not included with JIRA), please verify that they will be compatible with the version of JIRA you are upgrading to. You can find a plugin's compatibility information from the the plugin's home page on the Atlassian Plugin Exchange. Once you have confirmed the availability of compatible versions, you should upgrade your plugins after successfully upgrading JIRA. This can be done via the 'Plugin Repository' in your Administration Console.
  6. Test first!— We strongly recommend performing your upgrade in a test environment first. Do not upgrade your production JIRA server until you are satisfied that your test environment upgrade has been successful.
    • If you have any problems with your test environment upgrade which you cannot resolve, create an issue at our support site so that we can assist you.
    • If you have any problems during the upgrade of your production JIRA server, do not allow your users to start using this server. Instead:
      • Continue to use your old JIRA server — this will help ensure that you do not lose production data.
      • Also create an issue at our support site so that we can help you resolve the problems with production JIRA upgrade.

2. Backing Up

(warning) Before you begin the JIRA upgrade, we strongly recommend that you back up your existing JIRA installation because you cannot roll back a JIRA upgrade (after step 3.3).

2.1 Back up your database

Perform a backup of your external database (using your database's native backup tools) and verify that the backup was created correctly.

  • If your database's native backup tools do not allow you to perform an 'online backup' of the database (i.e. typically a 'snapshot' of the database), you should prevent users from updating your existing JIRA data (to ensure structural consistency of your database backup) by temporarily restricting access to JIRA.
    (warning) Inconsistent database backups may not restore correctly! If you are unfamiliar with your database's native backup/restore facilities, then before proceeding, test your database backup's integrity by:
    • restoring the database backup to a different (test) system and
    • connecting a test instance of your current JIRA version to this restored database.
  • JIRA's 'internal' database is HSQLDB, which should be used for evaluating JIRA only. If you happen to accidentally use the HSQLDB database for a production system, use the Migrating JIRA to Another Server instead of this one.

2.2 Back up your JIRA Home directory

Ensure JIRA is shut down before continuing.

The location of this directory is defined within the jira-application.properties configuration file, which is located inside the WEB-INF/classes directory within your 'JIRA Installation directory'.

(info) If you are using the JIRA WAR-EAR edition running on Apache Tomcat, your 'JIRA Installation directory' is typically located within the webapp directory.

2.3 Back up your attachments directory if located outside your JIRA Home directory

Your attachments directory may be located outside your JIRA Home directory. If so, it will also need to be backed up. To confirm the location of your attachments directory, refer to Configuring File Attachments.

2.4 Back up your JIRA Installation directory

The 'JIRA Installation directory' is the directory into which the JIRA application files and libraries were extracted when JIRA was installed. This directory is also sometimes called the 'JIRA Install directory'.

3. Performing the Upgrade

Icon

If you are running a 'mission-critical' JIRA server, we highly recommend performing the remaining steps of this guide in a test environment (e.g. using a copy of your JIRA database and JIRA Home directory) before performing the upgrade for production use.

3.1 Install the new version of JIRA

First, you must start with a fresh installation of your new JIRA version.

Download and extract the JIRA distribution you require, to a new directory. Do not overwrite your existing JIRA installation. Simply shut this down and install the new JIRA version to a new location.

Follow the installation instructions for either:

(info) If you are using JIRA WAR-EAR, remember to build your new JIRA web application and deploy it to your server. For specific instructions, read the relevant guide (specific to your application server) within the Installing JIRA WAR-EAR section.

3.2 Migrate your existing JIRA configurations over to your new JIRA installation

You may have modified a number of properties within configuration files of your existing JIRA installation.

If so, you need to make the same modifications in your new JIRA installation. However, do not simply copy configuration files from your existing JIRA installation and replace the equivalent files in your new JIRA installation, since the properties in these files may have changed from the old version.

For each file you have modified in your existing JIRA installation, you need to manually edit each equivalent file in your new JIRA installation and re-apply your modifications.

The following files are commonly modified in JIRA installations:

File

JIRA Standalone location

JIRA WAR-EAR location

Description

jira-application.properties

atlassian-jira/WEB-INF/classes

webapp/WEB-INF/classes

Advanced JIRA configuration properties

setenv.bat (Windows) or setenv.sh (Linux)

bin

Application Server's bin directory

Increasing JIRA Memory

osuser.xml

atlassian-jira/WEB-INF/classes

webapp/WEB-INF/classes

Modified if you have integrated LDAP with JIRA, integrated Crowd with JIRA, or if you are using a custom form of external user management or user authentication.

seraph-config.xml

atlassian-jira/WEB-INF/classes

webapp/WEB-INF/classes

Modified if you have integrated Crowd with JIRA.

(tick) The version-specific upgrade guides contain details on properties which may have changed in these commonly modified files.

In addition to the files above, you should also consider and/or perform the following configurations as part of the upgrade process:

  • Using JIRA with Atlassian's Crowd? — If you are using Crowd with JIRA, configure your new JIRA to talk to Crowd as described in Integrating Crowd with JIRA.
  • Allocating additional memory to JIRA — If you had previously allocated additional memory to JIRA, do the same for your new JIRA instance. For more information refer to Increasing JIRA memory.
  • Plugins — For any plugins that you had installed in your old JIRA:
    1. Download the plugin version for your new version of JIRA from the http://plugins.atlassian.com site.
    2. Install the JAR file(s) in your new JIRA, and carry out any other required installation for the plugin.
    3. If the plugin has a properties file, apply the same changes to it as you had in the old properties file (don't just copy over the old properties file).
  • Character encoding — Please ensure that character encoding (ie. locale) is the same on the new and old locations. You may have problems with encoding of the file names, if attachments are moved between two system with incompatible encoding.
    (warning) Your new version of JIRA may not function correctly or could encounter problems or errors if these are not implemented.
  • Customisations — If you had made any customisations (code, templates or configuration files), copy over compatible versions of these changes to the new JIRA. (The developers within your organisation who made the customisations to your old version will need to build and test equivalent changes for the new version, and provide you with the files to copy to your new JIRA).
  • (Optional) Disabling Email Access — If you need to perform some initial tests on your new JIRA installation, you can disable its email access to prevent unintended emails being sent during testing. Be sure to re-enable email access once any testing is complete.
  • (Optional) Running JIRA on a different port — If your new JIRA is installed on the same machine as your old JIRA, you may wish to make sure it runs on a different port (in case you ever need to restart your old JIRA).

3.3 Connect your new JIRA to your existing database

Now you need to configure your new JIRA installation to connect to and use your existing database, which was backed up (above).

(warning) Once you have performed this step and start your new JIRA server (in step 3.5 below), your JIRA database will be upgraded and it will no longer be compatible with earlier versions of JIRA.

(info) If you installed the JIRA EAR-WAR distribution and are connecting JIRA to an external database through a JDBC connection, ensure your database's JDBC driver has been copied across to the application server running your new JIRA installation. For details, refer to the appropriate instructions:

Configure your new JIRA installation to use your existing database.

  • If you prefer to manually configure your new JIRA installation to use your existing database, please note the following:
    • Instructions for manually configuring JIRA's database connections are located below the relevant JIRA Configuration Tool instructions (linked above).
    • If you had previously defined a Tomcat JNDI datasource connection to an external database and/or you implemented SSL, edit your new <Installation-Directory>\conf\server.xml and copy over the datasource connection definition and/or your SSL configurations from your old server.xml, along with any other relevant customisations.

3.4 Point your new JIRA to your existing JIRA Home directory

  1. Edit the jira-application.properties file found at WEB-INF/classes/jira-application.properties within your new JIRA 4.3.x Installation directory.
  2. Update the jira.home property in this file to the path of your existing JIRA Home directory, which you backed up (above).
    (info) For more information about this directory, see JIRA Home directory.
  3. Remove the '#' at the beginning of this line (so that JIRA no longer regards this line as a comment).
  4. Save your updated jira-application.properties file.

3.5 Start your new version of JIRA

  1. Verify that your old JIRA installation is shut down — if this JIRA server is still operating, shut it down.
  2. If you installed the JIRA WAR-EAR distribution within Tomcat, delete the Tomcat work directory before restarting JIRA. If you do not do this, users may encounter errors when they try to display JIRA pages.
  3. Start up your new version of JIRA. For:
    • JIRA Standalone — follow the Starting JIRA instructions.
    • JIRA WAR-EAR — follow the instructions for starting JIRA for your application server within the Installing JIRA WAR-EAR section.
      (info) During the startup process, your new JIRA installation will create any required database indexes.
  4. Visit JIRA in your web browser and log in using a username from your previous JIRA installation. You should be able to log in immediately, without seeing the Setup Wizard.
  5. Take a quick look around your JIRA site to confirm that your projects and issues are present and everything looks normal. You should see the new JIRA version number in the page footer.

Do not restart your old JIRA installation!

Icon


Your old JIRA installation may likely still be configured to use the same JIRA Home directory and database as your new JIRA installation. Running two separate JIRA installations which share a common JIRA Home directory and database can result in serious data corruption!

If you are concerned about accidentally starting your old JIRA installation (which you backed up above), you can delete your old JIRA installation directory.

4. Post Upgrade Checks and Tasks

It is strongly recommended that you perform the following checks and tasks after you have started your new instance of JIRA:
  1. Check your server logs for error messages, even if JIRA appears to be running correctly. If there are any errors there that you cannot resolve, create a support case in https://support.atlassian.com, attach your log file and we will advise you on the errors.
  2. If you were previously using External User Management, enable it in the new JIRA instance.
  3. If you changed machines when upgrading, change the paths to the indexes, attachments and backup directories, from within the Administration section of JIRA.
  4. Enable email, if you disabled it during testing.
  5. If you migrated any customisations from your old JIRA to the new JIRA, ensure that they are tested thoroughly.
    1. If you had downloaded plugins for the new version of JIRA, install the downloaded JAR file(s) in your new JIRA version and carry out any other required installation for the plugin.
    2. If the plugin has a properties file, apply the same changes to it as you had in the old properties file (don't just copy over the old properties file).

Congratulations! You have completed your JIRA upgrade.

See Also

Disabling Auto-Export