Upgrading JIRA

This page describes the recommended method of upgrading JIRA. With this method, you set up a new instance of JIRA, back up your data as an XML file from your existing JIRA instance, back up your attachments, and then restore that data into the new JIRA instance. The new JIRA will create the database structure (tables and indexes) before importing the data.

These instructions also apply to moving JIRA from one server to another server.

On this page:

Before you begin

Read the release notes and upgrade guide for the version you are upgrading to, as there may be version-specific instructions.
Check for known issues in the JIRA Knowledge Base.
Test first! — We strongly recommend that you carry out all of the following upgrade instructions in a test environment first. Do not upgrade your production JIRA until you are satisfied that the upgrade has been successful in your test environment.

If you have any problems with your test upgrade that you cannot resolve, create a support case in https://support.atlassian.com so that we can assist you.

If you have any problems during the upgrade of your production JIRA, do not allow your users to start using the new (upgraded) instance. Instead continue to use your old instance. This will help ensure that you do not lose production data. Create a support case in https://support.atlassian.com so that we can help you resolve the problems with the upgrade.

1. Set up a new instance of JIRA

1.1 Install the new version of JIRA

You will need to set up a new instance of JIRA that you can migrate your existing data into. This involves installing a new empty instance of the desired version of JIRA and applying configuration changes to match the configuration of your old instance of JIRA.

Download and unpackage the JIRA distribution you require, to a new directory. Do not overwrite your old JIRA instance. Follow the installation instructions, either:

Installing JIRA Standalone (recommended), or
Installing JIRA WAR-EAR (note: if you are running WAR-EAR, read the latest instructions for your application server and perform any necessary configuration steps. E.g. If your application server needs extra libraries to run JIRA, the extra libraries currently in your application server for the old JIRA may be outdated. Make sure you get the extra libraries needed for your new version of JIRA.)

1.2 Create a new, empty database

For example, if you are using a database 'jiradb' with your existing installation, and you are upgrading to JIRA 3.12, create database 'jiradb_312' with identical access permissions. Consult your database administrator if you need assistance with this.

(Note: you do not need to create a new database if you are using the embedded HSQL database).

1.3 Connect the new version of JIRA to the new, empty database

Follow the instructions for your preferred database:

1.4 Configure your new JIRA to have the same configuration as your old JIRA

You may have modified a number of configuration files in your existing JIRA instance. You need to make the same changes in your new JIRA instance. However, you cannot simply copy the file from your old instance, as the format may have changed from the old version to the new one. You need to manually edit all of the relevant lines in the new file, applying any changes you previously made to the file in your existing JIRA.

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.
propertyset.xml	`atlassian-jira/WEB-INF/classes`	`webapp/WEB-INF/classes`	Modified if you have integrated Crowd with JIRA.
seraph-config.xml	`atlassian-jira/WEB-INF/classes`	`webapp/WEB-INF/classes`	Modified if you have integrated Crowd with JIRA.

In addition to the above files, there are several other configuration changes that you may have to migrate:

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).
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).
Running JIRA on a different port — If your new instance of JIRA is installed on the same machine as your old JIRA, make sure it is running on a different port. For JIRA Standalone, refer to Changing JIRA Standalone's Port. For JIRA WAR-EAR, consult your application server documentation.
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.

1.5 Disable email access in your new JIRA

To prevent unintended emails being sent during testing, disable email access in your new JIRA instance.

1.6 (JIRA WAR-EAR only) Build the JIRA web application and deploy it to your application server

If you are using JIRA WAR-EAR, complete the setup of your new database by building your new JIRA web application and deploying it to your server. You can do this by running either the build.bat file (Windows) or the build.sh file (Unix). Read your application server guide to see if there are any server-specific instructions for building the web application. For example, there may be parameters you need to pass to the build script.

2. Migrate your existing JIRA data into your new JIRA instance

You now need to generate an XML backup of the data from your old JIRA instance, and import it into your new JIRA instance.

2.1 Ensure that users cannot update your old JIRA

You need to ensure that users cannot update your existing JIRA instance while you perform the XML backup, so that your backup will not contain inconsistent data.

You may want to set a banner (see Configuring an Announcement Banner) to warn users that JIRA will be inaccessible/read-only while an upgrade is performed.
There are two ways to ensure that users cannot update your existing JIRA instance:
- Make JIRA inaccessible: Shut down JIRA, start it on a different port to the one that JIRA usually runs on and do the backup there. Please note, no-one will be able to access JIRA while it is running on a different port during the backup, even to read issues; or,
- Make JIRA read-only: In your database, remove 'write' permissions from the database user (e.g. jirauser) that JIRA uses. If you do this, users will be able to read issues but will not be able to update them during the backup. For details, please see Making database read-only for upgrade backups.
Leave your existing JIRA inaccessible or read-only until the upgrade is completed successfully.

2.2 Create an XML export of the data from your old JIRA

You now need to export your data from your existing JIRA instance in preparation for the import into your new database.

After you have ensured that users cannot update your existing JIRA, generate the XML backup. Read the instructions on 'Backing up data' for details of how to do this.

2.3 Back up your attachments

Back up your attachments as described in the 'Backing up data' document.

2.4 Start the new JIRA

The final step of upgrading your JIRA is to start your new JIRA instance and import the data from your old JIRA instance.

If you haven't already done so, shut down your old JIRA instance by stopping the JIRA server.
If you are using Tomcat with your installation of JIRA (note: JIRA Standalone ships with Tomcat by default), 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.
Start up your new instance of JIRA:
- JIRA Standalone: Follow the Starting JIRA instructions.
- JIRA WAR-EAR: Follow the instructions for starting JIRA for your application server.

2.5 Import your old JIRA data into your new JIRA

After you have successfully started your new JIRA instance, you will need to import the data from your old instance into the new instance. You will need the backup file of data from your old JIRA that you created earlier in these instructions.

To import your old JIRA data into your new JIRA,

Access JIRA via your web browser. You will see the Setup Wizard.
Click the 'import your existing data' link.
The 'Import Existing Data' page will be displayed.
- In the 'File name' field, specify the XML backup file you created previously.
- In the 'Index Location' field, specify a different directory from your old JIRA.
Restore the attachments directory that you backed up previously, into the attachments directory of your new JIRA. (See Restoring Data.]
It is recommended that you avoid passing through a proxy when performing an XML restore, especially if your JIRA instance is very large. Using a proxy may cause timeout errors.

Note: JIRA will re-index the data automatically.

If the import is taking a long time, you may be able to get better performance by Increasing JIRA Memory temporarily.

2.6 Post-startup checks and tasks

It is strongly recommended that you perform the following checks and tasks after you have started your new instance of JIRA:

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.
If you were previously using External User Management, enable it in the new JIRA instance.
If you changed machines when upgrading, change the paths to the indexes, attachments and backup directories, from within the Administration section of JIRA.
Enable email, if you disabled it during testing.
If you migrated any customisations from your old JIRA to the new JIRA, ensure that they are tested thoroughly.

Congratulations! You have completed your upgrade of JIRA.

Troubleshooting

Check for known issues in the JIRA Knowledge Base.
If the upgrade fails for any reason, revert to using your old JIRA. Create a support case in https://support.atlassian.com and attach your log file, so that we can help you resolve the problems with the upgrade.
If your XML import fails with an error message indicating an invalid XML character, use our XML cleaner utility.

Child pages