This document describes how to migrate/upgrade to JIRA 6.3 on different server hardware or in a different server environment that entails one or more of the following:
If you are upgrading to a newer version of JIRA during the migration, please see Upgrading JIRA for information on the pre-requisite tasks you need to complete before upgrading.
On this page:
Icon
We strongly recommend performing your migration in a test environment first. Do not migrate your production JIRA server until you are satisfied that your test environment upgrade has been successful.
Some anti-virus or other Internet security tools may interfere with the migration and prevent the process from completing successfully. If you experience or anticipate experiencing such an issue with your anti-virus/Internet security tool, disable this tool first before proceeding with the JIRA migration.
During the upgrade process, you'll export JIRA's database from your existing JIRA installation (via an XML backup) and then restore this backup into a new JIRA installation. To ensure that the data in the XML backup is consistent with the latest data in the system, you must temporarily restrict access to JIRA so users can't update the data. Refer to the Preventing users from accessing JIRA during backups page for more information.
Be aware! Inconsistent XML backups cannot be restored!
Perform an XML backup of your existing JIRA installation's external database. For large JIRA installations, this process may require several hours to complete.
Icon
The 'embedded database' is the HSQLDB database supplied with JIRA for evaluation purposes only. If you accidentally use the HSQLDB database in a production system, perform an XML backup of this database and continue on with this procedure.
If the attachments and index directories are located outside of your JIRA Home Directory, you must back them up separately. These pages describe how to find out where these directories are located in your implementation:
Also refer to Backing Up Data for more information about backing up attachments in JIRA.
The 'JIRA Installation Directory' is the directory into which the JIRA application files and libraries were extracted when JIRA was installed.
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 separate test JIRA database and a copy of your JIRA Home directory) before performing the upgrade for production use.
First, you must start with a fresh installation of JIRA, either the current version or a newer one. If you are upgrading JIRA during this process, please see Upgrading JIRA for information on the pre-requisite tasks you need to complete before upgrading.
Download and extract the JIRA distribution you require, to a new directory. Do not overwrite your existing JIRA installation. Ensure this has been shut down and install the new JIRA version to a new location.
Follow the installation instructions for either:
If you are using JIRA WAR, remember to build your new JIRA web application and deploy it to your server. For specific instructions, refer to the JIRA WAR installation page for your application server within the Installing JIRA WAR section.
If your new JIRA 6.3 installation is on a new server, copy the backup of your existing JIRA Home Directory from the old server to the new server before proceeding.
To set up a "recommended" (not WAR) distribution:
To set up a WAR distribution:
You can also set your JIRA Home Directory's location by defining an operating system environment variable JIRA_HOME. This value of this variable takes precedence over the value of the jira.home property in the jira-application.properties file in your JIRA Installation Directory. See Setting your JIRA Home Directory for details.
Create a new, empty database that your new JIRA installation will use to store its data.
Follow the appropriate 'Connecting JIRA to...' instructions for your database from stage 2, although from stage 4 of that procedure, be aware of the yellow note below:
Icon
If you are using a database (called jiradb, for example) with your existing JIRA installation and the database for your new JIRA installation is running on the same machine or database server, create your new database with a different name (e.g. something intuitive like jiradb_440 for JIRA 4.4.0). However, ensure the new database has identical access permissions to the old JIRA database. Consult your database administrator if you need assistance with this.
You do not need to create a new database if you are using the embedded HSQL database.
If you have modified properties in configuration files of your existing JIRA installation, make the same modifications in your new JIRA installation. However, because the properties in the configuration files may have changed between versions, you cannot simply copy the configuration files from your existing installation and replace the equivalent files in the new installation.
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. If a file is not present in your new JIRA installation (for example, osuser.xml in recent JIRA versions), then simply copy that file over to your new JIRA installation.
The table below lists the most commonly modified files and their locations within your JIRA Installation Directory:
File |
Location in 'recommended' (formerly 'Standalone') JIRA distributions |
Location in JIRA WAR |
Description |
jira-application.properties |
atlassian-jira/WEB-INF/classes |
webapp/WEB-INF/classes |
Location of the JIRA Home Directory and Advanced JIRA Configuration in JIRA 4.3.x and earlier. Any custom property values defined in the jira-application.properties file of your existing JIRA 4.3.x (or earlier) installation must be migrated across to the jira-application.properties file of your new JIRA 6.3 installation before you start your new JIRA installation. Upon starting your new JIRA installation, any custom property values in the jira-application.properties file will automatically be migrated across to either the JIRA database or jira-config.properties file. jira.home is the only property of the jira-application.properties file subsequently used by JIRA. |
setenv.bat (Windows) or setenv.sh (Linux) |
bin |
Application server's bin directory |
|
osuser.xml (not required if upgrading from JIRA 4.3.0 or later) |
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. |
server.xml |
conf |
Application server's conf directory |
Modified in the following situations:
|
The version-specific upgrade notes 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:
Do not restart your old JIRA installation...
Icon
If your new JIRA 6.3 installation is on the same server as your old one, it may still be configured to use the same JIRA Home directory as your new JIRA installation. Running two separate JIRA installations which share a common JIRA Home directory can lead to serious data corruption.
Nevertheless, we recommend that you do not delete any aspect (or backed up component) of your old JIRA installation, until you are satisfied that your upgraded JIRA installation is functioning as expected.
After you have started your new JIRA installation, 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 (above).
To import your old JIRA data into your new JIRA:
It is strongly recommended that you perform the following checks and tasks after you have started your new instance of JIRA:
Congratulations! You have completed your JIRA migration/upgrade.
Disabling Auto-Export Restoring Data Upgrading JIRA Switching Application Servers to Apache Tomcat Switching Databases