This document describes how to migrate/upgrade to JIRA applications on different server hardware, or in a different server environment that entails one or more of the following:
- a new operating system that will run JIRA applications,
- new locations for storing your index and/or attachments, or
- a new database or database system that will store JIRA application data.
If you are upgrading to a newer version of JIRA applications during the migration, please see Upgrading JIRA applications for information on the pre-requisite tasks you need to complete before upgrading.
If you’re changing your operating system from Windows to Linux, or vice versa, remember that you will need to reverse the ‘slashes’ when required in your file paths (‘/’ to ‘\’, or ‘\’ to ‘/’).
1. Before you start
- Check your license – Verify that your license support period is still valid.
- Check for known issues – Use the JIRA Knowledge Base to search for any issues in the new version that will affect you.
- Check for compatibility:
- Confirm that your operating system, database, other applicable platforms and hardware still comply with the requirements for JIRA applications.
- Make sure the source and target instances are initially set with the same timezones to avoid any issues with date and time fields.
- If you have installed JIRA application add-ons (i.e. not included with JIRA applications), verify that they will be compatible. You can find a add-on’s compatibility information from the the add-on’s home page on the Atlassian Marketplace. You can also follow the procedure outlined here: Checking add-on compatibility with application updates to have the Universal Add-on Manager help you with this.
We strongly recommend performing your migration in a test environment first. Do not migrate your production JIRA server application until you are satisfied that your test environment upgrade has been successful.
- If you have any problems with your test environment which you cannot resolve, create an issue at our support site so that we can assist you.
- If you have any problems during the migration of your production JIRA server application, do not allow your users to start using this server. Instead:
- Continue to use your old JIRA server application — 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 your migration.
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 application migration.
2. Backing up
2.1 Stop users from updating JIRA data
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 applications during backups page for more information.
Be aware! Inconsistent XML backups cannot be restored!
2.2 Back up your database
Perform an XML backup of your existing JIRA installation’s external database. For large JIRA installations, this process may require several hours to complete.
The ’embedded database’ is the H2 database supplied with JIRA for evaluation purposes only. If you accidentally use the H2 database in a production system, perform an XML backup of this database and continue on with this procedure.
2.3 Back up your JIRA home directory
- Shut down JIRA.
- Locate the JIRA home directory. You can find information about the location of the directory by navigating to the
<jira-application-dir>/WEB-INF/classes/jira-application.propertiesfile in your JIRA application installation directory. Alternatively, you can open the JIRA configuration tool to see the directory that is set as your JIRA Home. - Navigate to the directory specified in the configuration file and create a backup of it in another directory.
Delete the file <jira-home>/dbconfig.xml from the original folder as soon as the backup is complete.
Delete the file <jira-home>/dbconfig.xml from the original folder as soon as the backup is complete.2.4 Back up your attachments and index directories if located outside your JIRA home directory
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:
- Your attachments directory — Refer to Configuring file attachments page in the documentation for your version of JIRA.
- Your index directory — Refer to Search indexing page in the documentation for your version of JIRA.
Also refer to Backing up data for more information about backing up attachments in JIRA.
2.5 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.
3. Setting up your new JIRA application installation
If you are running a ‘mission-critical’ JIRA server application, we highly recommend performing the remaining steps of this guide in a test environment (e.g. using a separate test JIRA application database and a copy of your JIRA application home directory) before performing the upgrade for production use.
3.1 Install the new version of your JIRA applications
First, you must start with a fresh installation of your JIRA applications, either the current version or a newer one. If you are upgrading JIRA applications during this process, please see Upgrading JIRA applications for information on the pre-requisite tasks you need to complete before upgrading.
Download and extract the JIRA application distribution you require, to a new directory. Do not overwrite your existing JIRA application installation. Ensure this has been shut down and install the new JIRA application version to a new location.
3.2 Point your new JIRA application to (a copy of) your existing JIRA application home directory
- Open the JIRA configuration tool.
- Click the JIRA Home tab.
- Update the JIRA Home Directory field:
- If your JIRA 7.1 installation is on a new server, update the JIRA Home Directory field to the path of your copied JIRA Home directory.
- If your JIRA 7.1 installation is on the same server, update the JIRA Home Directoryfield to the path of your existing JIRA Home directory.
For more information about this directory, see JIRA home directory.
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.
3.3 Connect the new version of your JIRA application to a new, empty database
- Connecting JIRA to PostgreSQL
- Connecting JIRA to MySQL
- Connecting JIRA to Oracle
- Connecting JIRA to SQL Server 2008
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 H2 database.
3.4 Migrate your existing JIRA application configurations over to your new installation
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 | Description |
|---|---|---|
| jira-application.properties | atlassian-jira/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 7.1 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.propertiesfile subsequently used by JIRA. |
| setenv.bat (Windows) or setenv.sh (Linux) | bin |
Increasing JIRA Memory |
| osuser.xml (not required if upgrading from JIRA 4.3.0 or later) |
atlassian-jira/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 |
Modified if you have integrated Crowd with JIRA. |
| server.xml | conf |
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:
- 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.
- Remember to configure Crowd to grant JIRA’s new hostname/IP access.
- 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, download the plugin version for your new version of JIRA from the http://plugins.atlassian.com site.
- Character encoding — Ensure that character encoding (i.e. locale) is the same on the new and old locations. Your new version of JIRA may not function correctly if attachments are moved between two system with incompatible encoding.
- Customizations — If you had made any customizations (code, templates or configuration files), copy over compatible versions of these changes to the new JIRA. (The developers within your organization who made the customizations 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 upgraded JIRA installation.)
- (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). See Changing JIRA’s TCP ports for details.
3.5 Start your new JIRA application version
- Verify that your old JIRA installation is shut down — if this JIRA server is still operating, shut it down.
- Start up your new version of JIRA by follow the Starting JIRA instructions.
Do not restart your old JIRA installation…
If your new JIRA 7.1 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.
3.6 Import your old data into your new JIRA applications
- Restore the attachments directory that you backed up previously into the attachments directory of your new JIRA. (See Restoring data.)
- Start JIRA.
- In the setup wizard, select Import existing data.
- In the File name field, specify the XML backup file you created previously during the export process (above). The zipped file should contain two xml files:
activeobjects.xmlandentities.xml. Both of these files must be included in the zipped file for the import process to work.
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. - Access JIRA via your web browser again and log in using a username from your previous JIRA installation.
- 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.
4. Post migration checks and tasks
It is strongly recommended that you perform the following checks and tasks after you have started your new JIRA application instance:
- Check your server logs for error messages, even if JIRA applications appear to be running correctly. If there are any errors there that you cannot resolve, create a support case, 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 application instance.
- If you changed machines when upgrading, change the paths to the indexes, attachments and backup directories, from within your application’s JIRA Administration section.
- Enable email, if you disabled it during testing.
- If you migrated any customizations from your old to new JIRA applications, ensure that they are tested thoroughly.
- If you had downloaded plugins for the new JIRA application versions, install the downloaded JAR file(s) in your new version and carry out any other required installation for the plugin.
- 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 application migration/upgrade.
See Also
Disabling auto-export
Restoring data
Upgrading JIRA applications
Switching databases