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
Create an XML backup of your database.
Back up your installation directory and home directory.Where is my home directory?
You can find the location of your home directory in the
The default paths are:
C:\Program Files\Atlassian\Application Data\JIRA
As soon as the backup is complete, delete the
<home-directory>/dbconfig.xmlfile 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
3. Extract the file and upgrade JIRA
- Extract (unzip) the files to a new directory.
- Edit the
<installation-directory>\atlassian-jira\WEB-INF\classes\jira-application.propertiesfile to point to your existing JIRA home directory. Make sure that you deleted the
dbconfig.xmlfile, otherwise JIRA will try to connect to your existing database.
- Copy your jdbc driver jar file from your existing JIRA installation directory to
jira-atlassian/WEB-INF/libin your new installation directory.
- There are some additional steps you may need to take if:
you use Crowd for user managementClick 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)
4. Start JIRA and connect it to the database
- Start JIRA to launch the setup wizard. Go to
<installation-directory>/bin, and run the
- Access JIRA through your browser, and choose I'll set it up myself to get access to more setup options.
- Select My own database, and provide details of a new, empty database.
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.
- 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.bat file ), you'll need to reapply the customizations to the relevant files in the newly upgraded JIRA installation directory.
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.
- Stop your upgraded JIRA instance.
- Reapply the customizations to the relevant files in the upgraded JIRA installation directory.
- 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.
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.