Upgrading JIRA applications with a fallback method
If you're upgrading from a version of JIRA earlier than 7.0, you should consult the Migration hub. The release of JIRA 7.0 contained functionality that affects your user management, application access and log in permissions, and your JIRA installations setup, and it's very important that you understand the requirements and the implications before you upgrade. The Migration hub has all this information in one handy space.
This page describes how to upgrade JIRA 4.4.x or later in a way that allows you to safely roll back to your previous system if the upgrade process takes longer than expected, or if you encounter issues. This method is especially useful for enterprise environments and for organizations where JIRA is mission-critical for the business. You can also use this method so you have a fallback option if you are performing a complex system change, such as changing the operating system that will run JIRA, the database that will store JIRA's data or the location of JIRA's index and/or attachments paths.
Because this process is designed to provide the safest possible upgrade method, it requires advanced knowledge of database administration tasks. We recommend you have the following resources and/or skill sets available for your upgrade:
- Database administrator - for general production-level database administration (i.e. run backups, create, remove, restore, etc.)
- JIRA application administrator - for general application administration and upgrade managment (i.e. JIRA SME, user with System Administrator privileges and deep understanding of application and associated dependencies within your organization.)
- Systems/Network administrator - for managing systems and networks (i.e. proxy servers, DNS changes, monitoring, VM's, hardware, etc.)
This upgrade process also requires you to make backups of your database, which can be time-consuming. Customers with large JIRA environments should plan for four hours of downtime. If you know your system takes several hours to re-index, you might want to allocate more than four hours for the upgrade.
See Upgrading JIRA applications for more information on the methods you can use to upgrade JIRA.
This graphic illustrates the process described in this document. For simplicity, the illustration shows how you can perform an upgrade using two different pieces of hardware. However, you can just as easily install JIRA in different directories on the same server to test and perform an upgrade. In this case, simply ensure that you use separate installation and database directories during the testing.
Before you start
- Read about the new version - Review the release notes and upgrade notes for the version of JIRA that you are upgrading to. See our Release notes for JIRA Server. If you plan to skip a few JIRA versions during your upgrade, we strongly recommend that you read the upgrade guides for all major versions between your current version and the version to which you are upgrading.
- 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 7.3. The End of Support Announcements page also has important information regarding platform support for future versions of JIRA.
- If you have installed JIRA plugins (i.e. not included with JIRA), verify that they will be compatible with the version of JIRA you are upgrading to. You can find a plugin's compatibility information from the plugin's home page on the Atlassian Marketplace.
- Some anti-virus or other Internet security tools may interfere with the JIRA upgrade process 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 before proceeding with the JIRA upgrade.
- Prestaging and testing your new version of JIRA - We strongly recommend performing your upgrade in a test environment first. Do not upgrade your production JIRA server until you are satisfied that your test environment upgrade has been successful.
- If you have any problems with your test environment upgrade which you cannot resolve, create an issue at our support site so that we can assist you.
- If you have any problems during the upgrade of your production JIRA server, do not allow your users to start using this server. Instead:
- Continue to use your old JIRA server — 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 upgrade.
If you have any problems during the upgrade process, create an issue at our support site so that we can help you resolve the problems with your upgrade. We strongly recommend that you perform the below procedure first as a test only. This will allow you to note any complications (e.g. with customized settings or add-ons) ahead of time so that you can minimize the downtime of the system.
1. Prepare your production instance for upgrade
When you begin preparing to upgrade, it's best practice to halt any major changes to your production system (such as plugin upgrades, customizations, etc.). Keeping your production system as stable as possible will make testing the upgrade version simpler.
It's also a good idea to let your users know about planned downtime, either through email or by using JIRA's announcement banner.
2. Set up a proxy server
Before beginning the upgrade process set up a reverse proxy, such as a load balancer. The proxy server allows you to redirect users to a different JIRA server without having to wait for a DNS change - this change will be invisible to the end-user. If, at any point during the upgrade process, you encounter issues you can't resolve and you need to rollback to your existing JIRA instance, simply restart your existing JIRA instance and reconfigure the proxy server to point to the old server.
If you use monitoring, API calls (such as SOAP, REST, or CLI), or scripts associated with your production server, update them with the new proxy information.
Please see the following documentation for further information on configuring Apache:
3. Disable the old JIRA production instance and start the new instance
Before disabling your old JIRA production instance, identify the location of your attachments and index directories. If they are located outside of your JIRA home directory, you will back them up manually later during the upgrade process. These pages describe how to find out where these directories are located in your environment:
- Your attachments directory — Refer to the Configuring file attachments page for your version of JIRA.
- Your index directory — Refer to the Search indexing page for your version of JIRA.
If your attachments and index directories are located outside of the JIRA home directory, note their location so you can easily find them later.
After you've located the attachments and index directories, disable the old JIRA production instance so you can perform a database backup:
- Shut down your old production JIRA instance (for example, by executing either the
/bin/stop-jira.shor\bin\stop-jira.batfile in your JIRA application installation directory, or by stopping the JIRA service). - Using your database's native backup tools, perform a backup of the data in your old production JIRA instance. See Backing up data.
Set the newest copy of the production database as the new database for production.
Make sure that the database set up for the new production version of JIRA is clearly distinguishable from the database backup of your old production JIRA, and that the new production instance is not configured to connect to the old production database.
- Synchronize the JIRA attachment directories:
- 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.
If the attachments and index directories are located outside of your JIRA home directory, you must back them up separately. (See the beginning of this task for information on how to find these files.)
Also refer to Backing up data for more information about backing up attachments in JIRA.
- Replace the JIRA home directory (and the attachment and index directories, if separate from the JIRA home directory) in the new JIRA production environment with the backups you made of the old production directories.
- Locate the JIRA home directory. You can find information about the location of the directory by navigating to the
Start the new version of JIRA in your new production environment. When you start this version, JIRA will upgrade your data and may perform a re-index. When the re-indexing is complete, verify that your data is present and that there are no issues with the system.
The re-indexing may take up to several hours, depending on the size of your instance. If you know that your instance takes a long time to index, make sure to plan your scheduled downtime accordingly.
Reconfigure the proxy server you set up in step 2 so that the new version of JIRA becomes your production instance. Make sure to let your users know about the new instance (including the new domain name) and any changes that might affect them.
If you experience any issues in the new production environment, you can simply revert the proxy server settings and re-instate your old production instance until you can resolve the issue.
4. Post upgrade checks and tasks
It is strongly recommended that you perform the following checks and tasks after you have started your new instance of JIRA:
- Check your server logs for error messages, even if JIRA appears 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 instance.
- If you changed machines when upgrading, change the paths to the indexes, attachments and backup directories, from within the Administration section of JIRA.
- Enable email, if you disabled it during testing.
- If you migrated any customizations from your old JIRA to the new JIRA, ensure that they are tested thoroughly.
- If you had downloaded plugins for the new version of JIRA, install the downloaded JAR file(s) in your new JIRA 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).
- Once you have confirmed that the new server is working correctly, ensure that the production license is updated for the new server ID, as follows:
- Log in to https://my.atlassian.com.
- Locate the appropriate license.
- Edit the Server ID, as per the new production Server ID, and save it.
- Update the production license in the new server.
Once you have confirmed the availability of compatible versions, you should upgrade your plugins after successfully upgrading JIRA. This can be done via the 'Plugin Repository' in your Administration Console. It is recommended that you re-index JIRA after upgrading your plugins.
Congratulations! You have completed your JIRA migration/upgrade.