Upgrading JIRA applications with a fallback method
This page describes how to upgrade JIRA 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, and you can't allow prolonged downtime.
About the upgrade
You'll need to set up a proxy server to have a quick way of redirecting your users either to the existing or to the new instance of JIRA. Then, you'll replicate your existing environment and upgrade the new instance. This is required to preserve your existing environment and have a fallback option, if the upgrade is unsuccessful, or if you simply prefer the old version.
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.
Upgrading JIRA with a fallback method
1. 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. If, at any point during the upgrade process, you encounter issues you can't resolve, you can 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:
2. Disable your existing JIRA and create backups
Disable your existing JIRA, so that users don't create new data. Next, create backups of your database, and the home and installation directories.
- Back up your database and confirm the backup was created properly.
You can use the database native tools to create the backup.
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
3. Set up a new instance of JIRA
The easiest way to set up a new environment is to use the procedure described in Establishing staging environments to copy the whole JIRA into a new directory. You can also install the new instance, and then restore the database, home directory, and all your customizations.
4. Upgrade your new JIRA
Perform a regular upgrade. For more info, see Upgrading JIRA using the installer.
5. Verify the upgrade and redirect the proxy
Take a look around your new instance and verify that everything is working properly.
- If you're happy with the outcome, redirect the proxy server to the new instance.
- If something is not right, redirect the proxy server to the old instance. Your users can resume work, while you prepare for the new upgrade.