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:

  • 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.

Migrating Jira to another server

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. 

1. Back up

  1. Create an XML backup of your database.

    Show me how to do this...

    You can create an XML backup in the Jira UI. To keep the database consistent, you should stop your users from making any changes.

    a. Stop users from updating Jira data.

    b. Perform an XML backup.

  2. Back up your installation directory and home directory.

    Where is my home directory?

    You can find the location of your home directory in the <installation-directory>/atlassian-jira/WEB-INF/classes/jira-application.properties file.

    The default paths are:

    Windows: C:\Program Files\Atlassian\Application Data\JIRA

    Linux: /var/atlassian/application-data/jira

  3. As soon as the backup is complete, delete the <home-directory>/dbconfig.xml file from the copy of your home directory that you'll be using for the new installation. This will allow you to connect Jira to a new database.

2. Download Jira

Download the zip or tar.gz archive – Jira Core or Jira Software.

3. Extract the file and upgrade Jira

  1. Extract (unzip) the files to a new directory.

  2. Edit the  <installation-directory>\atlassian-jira\WEB-INF\classes\jira-application.properties file to 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.

  3. Copy your jdbc driver jar file from your existing Jira installation directory to  jira-atlassian/WEB-INF/lib  in your new installation directory.

  4. There are some additional steps you may need to take if: 

      • you use Crowd for user management

        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/osuser.xml (4.3.0 and earlier)

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

4. Start Jira and connect it to the database

  1. Start Jira to launch the setup wizard. Go to <installation-directory>/bin, and run the start-jira.sh / start-jira.bat file.
  2. Access Jira through your browser, and choose I'll set it up myself to get access to more setup options.
  3. Select My own database, and provide details of a new, empty database.
  4. On the next screen, click Import your data, and select the file with your XML backup.

    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.
  5. Follow instructions on the screen to complete the setup. 
  6. 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.

After the migration

5. Re-apply any modifications

If you have customized Jira (such as an SSL configuration in the server.xml file, or additional memory allocation in the setenv.sh / setenv.bat file ), you'll need to reapply the customizations to the relevant files in the newly upgraded Jira installation directory.

Show me how to do this...

Any other configurations or customizations (including any other modifications in the server.xml file) are not migrated during the upgrade and need to be reapplied manually.

  1. Stop your upgraded Jira instance.
  2. Reapply the customizations to the relevant files in the upgraded Jira installation directory.
  3. Restart the upgraded Jira instance.

We strongly recommend you test your customizations in a test instance prior to upgrading your production instance as changes may have been made to Jira that make your customizations unusable.

Show me the list of important files...

If you're unsure which files you might have modified, take a look at the list of important files in the Jira installation directory.


Did something go wrong?

Check the resources on our Support page, or raise an issue so we can help you resolve your problem.

Your existing Jira installation should be intact. You can restart it and resume your work.

Last modified on Aug 14, 2019

Was this helpful?

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