Migrating Jira applications to another server

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:

  • new operating system

  • new locations for storing your index and/or attachments

  • new database or database system

To migrate Jira to a new server or location, you'll need to install a new Jira instance. Once you've completed the installation, you'll migrate your existing data between the databases, and then move your home directory and all existing customizations. 

tip/resting Created with Sketch.

Jira Data Center Migration App

If you're planning to migrate your Jira instance to clustered infrastructure on AWS, consider using the Jira Data Center Migration App. This app will automate the customization and deployment of AWS infrastructure; afterwards, it'll also walk you through the migration process. For detailed information, see How to use the Data Center Migration app to migrate Jira to an AWS cluster.

Back up

  1. Create a backup of your database. For details, see . 

    1. Stop users from updating data in Jira.
    2. Backing up data
  2. Back up your installation and home directory.

  3. As soon as the backup is complete, delete the <home-directory>/dbconfig.xml file from your existing home directory. This will remove the existing connection between Jira and your database, and allow you to connect to a brand new database.

Download Jira

  1. Download one of the Jira applications from our website. Choose the zip or tar.gz archive.

If you're upgrading both Jira Core/Software and Jira Service Desk, upgrade Jira Core/Software only. You'll later upgrade Service Desk directly in Jira, without a separate installer.

Extract the files

Extract the archive you've downloaded, and start the upgrade.

  1. Stop your existing Jira instance.

  2. Extract (unzip) the files to a directory (this is your new installation directory, and must be different to your existing installation directory). 

  3. Edit the following file:


    It must point to your existing Jira home directory. Make sure that you deleted the dbconfig.xml file, otherwise Jira will try to connect to your existing database. 

  4. (Optional) If you use Crowd for user management, complete these extra steps.

    Click here to expand...

    If you are using Crowd for user management, reapply the modifications from the following files from your existing installation directory to the new files. Do not copy the files as they may be different in the new version of Jira.

    • <Installation-Directory>/atlassian-Jira/WEB-INF/classes/crowd.properties
    • <Installation-Directory>/atlassian-Jira/WEB-INF/classes/seraph-config.xml

Install the database driver

If you're using an Oracle or MySQL database, download a new JDBC driver. For other databases, you can omit this step.

tip/resting Created with Sketch.

If the driver is up to date, you can also copy it from your previous version.

  1. Download one of the following drivers:

    • Oracle: JDBC driver
    • MySQL: the latest JDBC driver.

  2. Place it in <installation-directory>/lib.

Re-apply any modifications

While using Jira, you’ve probably added some custom modifications to Jira files. These may include connection details, settings related to memory allocation, or other JVM arguments. In this step, you need to re-apply the same modifications to the new files by copying them from your backups.

Make sure you don't just copy over the old files, as the 'native' settings they contain might have changed between the Jira versions.

Some of the files we usually modify:

  • server.xml
  • dbconfig.xml
  • Jira-config.properties
  • setenv.sh / setenv.bat (memory allocation and other JVM arguments)
  • for more, see Important files in Jira

Start Jira for the first time

Start your new Jira version, and connect it to the database.

  1. Go to <installation-directory>/bin, and run one of the following files:

    • Windows:  start-Jira.bat
    • Linux:  start-Jira.sh

  2. Open Jira in your browser.

  3. When prompted, choose I'll set it up myself to get access to more setup options.

  4. Select My own database, and provide details of a new, empty database.

  5. On the next screen, click Import your data, and select the file with your XML backup.

    Avoid passing through a proxy when importing your XML data, especially if your Jira instance is large. Using a proxy may cause timeout errors.

  6. Follow instructions on the screen to complete the setup. 

Restore your backup and attachments

Time to unpack your backup. For instructions, see Restoring data.

Almost there!

Your Jira instance has been migrated. Below you can learn how to upgrade Service Desk, if you have it, and how to upgrade your apps.

(Optional) Update Jira Service Desk

If you're using Jira Service Desk, you can update it directly in the UI, without downloading a separate installer.

  1. Go to Administration (> Applications > Versions and licenses.
  2. Update Jira Service Desk. This will automatically update Service Desk to a compatible version.

Upgrade apps (add-ons)

Upgrade your apps, so they're compatible with the new version.

  1. Go to Administration () > Manage apps > Manage apps.
  2. Upgrade your apps to the supported versions.

Rebuild index

Your old index is incompatible with the new version, and will be deleted by Jira. Run the reindex to rebuild it from scratch. This step might take some time, depending on how many issues and apps you have.

  1. Go to Administration (> Indexing, and run Lock Jira and rebuild index.
Last modified on Oct 8, 2020

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.