Documentation for JIRA 4.0. Documentation for other versions of JIRA is available too.
This page describes how to upgrade JIRA. Before you start, you should review the release notes and upgrade guide for the version you are upgrading to.
On this page:
In summary, the method for upgrading JIRA is to set up a new instance of JIRA, and then migrate your existing JIRA data into the new JIRA instance. There are two variations of this method, the difference being in how you choose to migrate your existing JIRA data.
With this method, you 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; or,
With this method, you take a copy of your existing JIRA database and configure the new JIRA to use the copied database. When you first start up the new JIRA it will upgrade the database to the structure needed for the new JIRA version.
We recommend that you use the "XML backup/restore" method, as the "Connect JIRA to a copy of your old database" method has the following restrictions:
The "Connect JIRA to a copy of your old database" method can be useful for extremely large installations, where the recommended method of "XML backup/restore" would take too long.
Overall, the process to upgrade JIRA takes five steps (four steps, if you are not performing an XML backup/restore to migrate your existing JIRA data):
Set up a new instance of JIRA:
1. Install the new instance of JIRA.
2. Configure your new JIRA to have the same configuration as your old JIRA.
Migrate your existing JIRA data:
3. Set up a new database.
4. (If doing an "XML backup/restore" method) Export your data from your old JIRA.
5. Start the new JIRA (including the import of your old data into your new JIRA instance, if doing an XML backup/restore).
If you are upgrading your 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, JIRA Standalone or JIRA EAR/WAR, to a new directory. Do not overwrite your old JIRA instance.
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 EAR WAR location |
Description |
entityengine.xml |
|
|
Used to configure the JIRA entity engine for your database type. Refer to the Configure the JIRA Entity Engine section of your database guide. |
osuser.xml |
|
|
Modified if you are integrating LDAP with JIRA, or if you are using a custom form of external user management or user authentication. |
jira-application.properties |
|
|
|
server.xml |
|
File and location varies per application server |
Modified when connecting JIRA to a database |
In addition to the above files, there are several other configuration changes that you may have to migrate:
The process for migrating your existing JIRA data into your new JIRA instance generally involves setting up a new/copied database, configuring it to work with your new instance of JIRA and populating it with data, if required. As previously described, you can choose to migrate your existing data by XML backup/restore (recommended) or by connecting JIRA to a copy of your old database.
The first step of migrating your existing data into your new JIRA instance is to set up a new database. If you are using the XML backup/restore method, you need to set up a new empty database. If you are using the Connect JIRA to a copy of your old database method, then you must take a copy of your old database for the migration. You will then need to configure JIRA to use your new database and if you are using JIRA EAR/WAR, build and deploy the JIRA web application.
If you are migrating your data to the new JIRA using the XML backup/restore method, create a new database (note, you do not need to create a new database if you are using the embedded HSQL 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 with your DBA if you need assistance with this.
"Do not use your existing database for the data migration"
If you are using the Connect JIRA to a copy of your old database method, it is critical that you take a copy of your existing database for the data migration. Do not just connect the new JIRA to your existing database, as it will be upgraded to the format required by the new JIRA version. Hence, if any problems occur with your upgrade, you will not be able to revert to using your old JIRA.
If you are migrating your data to the new JIRA using the Connect JIRA to a copy of your old database method, follow the steps below to create a copy of your existing database:
The following instructions describe how to configure JIRA to use your new database. The steps differ depending on whether you are using JIRA Standalone or JIRA EAR/WAR:
conf/server.xml
file in your old JIRA Standalone to get your new JIRA Standalone to use your database, but substitute the new database name (*jiradb_312 in the above example) in the JDBC URL.
common/lib
directory of your old JIRA Standalone to your new JIRA Standalone.If you are using JIRA EAR/WAR, 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.
If you are using the XML backup/restore method, you can now export your data from your existing JIRA instance in preparation for the import into your new database. To export your existing JIRA data into a backup file, follow the steps below:
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. You may want to set a banner to warn users that JIRA will be inaccessible/read-only while an upgrade is performed.
The final step of upgrading your JIRA is to start your new JIRA instance and, if you are using the XML backup/restore method, import the data from your old JIRA instance. As previously described, starting your new JIRA instance will automatically update your new/copied database.
Starting up JIRA using Tomcat 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.
If you are migrating your data to the new JIRA using the XML backup/restore method, you will need to import the data from your old instance into your new JIRA instance after you have successfully started it. 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,
We highly recommend that you perform the following checks and tasks after you have started your new instance of JIRA:
Congratulations! You have completed your upgrade of JIRA.