Upgrading JIRA Data Center

Upgrading JIRA applications

On this page

Related content

Still need help?

The Atlassian Community is here for you.

Ask the community

This page describes how to upgrade JIRA Data Center. During the upgrade, you'll shut down your JIRA instances, and then copy the new version to each node, upgrading them one by one. If you'd rather have your JIRA working during the upgrade, we recommend that you use  Managing zero downtime upgrades instead.

If you're currently using JIRA Software Server, learn more about upgrading to Data Center here.

Before you begin

Before you upgrade JIRA, there's a few questions you need to answer. 

Is this the right upgrade method for you?

Tell me more...

This method requires that you shut down JIRA on each of your nodes. It's mostly about upgrading one node, and then copying the upgraded directories to remaining nodes.

If you can't allow any downtime in your environment, you should use a different method: Managing zero downtime upgrades.

Are you eligible to upgrade?

Tell me more...

To check if software maintenance is current for your license, go to > Applications > Versions and licenses, and make sure the license support period has not expired.

If your support period has expired, follow the prompts to renew your license and reapply it before upgrading.

Have our supported platforms changed?
Tell me more...

Check the Supported Platforms page for the version of JIRA you are upgrading to. This will give you info on supported operating systems, databases and browsers.

Good to know:

  • If you need to upgrade your database, be sure to read the Upgrade Notes for the JIRA version you plan to upgrade to (and any in-between) to check for any database configuration changes that you may need to make.
Do you need to make changes to your environment?
Tell me more...

Newer JIRA versions sometimes require changes to your environment, such as providing more memory or adjusting your reverse proxy settings.

Good to know:

We use Upgrade Notes to communicate changes that will impact you, such as:

  • Changes to supported databases, memory requirements or other changes that will impact your environment.
  • Features that have significantly changed or been removed in this release.
  • Actions you may need to take in your instance or environment immediately after the upgrade.

It's important to read the notes for the version you're upgrading to and those in-between.

Plan your upgrade

1. Complete the pre-upgrade checks

  1. Check the Upgrade Notes for the version you plan to upgrade to (and any in between).

  2. Go to  > System > Support Tools, and check the results of the health check. Fix any detected problems.

    License expired?

    If the software maintenance period included in your license has expired, you can keep using JIRA, but you'll need to renew before you can upgrade.

    Go to > Applications > Versions and licenses, and follow the prompts to renew your license.

    Still using the embedded database?

    If you are using the embedded (trial) database, you should migrate to a different database before upgrading.

    This database is supplied for evaluation purposes only and is not recommended for production environments.

  3. Go to  > Add-ons, and scroll down to JIRA update check to check the compatibility of your add-ons. Choose the version you plan to upgrade to, then hit Check.

    If you have incompatible add-ons...

    If your users rely on particular add-ons, you may want to wait until they are compatible before upgrading JIRA. Add-on vendors generally update their add-ons very soon after a major release.

    Good to know:

    • Compatibility information is often not available immediately after a new release. In many cases, the add-on will still work, so give it a try in a test environment before upgrading the production one.

2. Upgrade JIRA in a test environment

  1. Create a staging copy of your current production environment.
    See Establishing staging server environments for help creating an environment to test your upgrade in.
  2. Follow the steps below to upgrade your test environment.
  3. Test any unsupported add-ons and customizations before upgrading your production environment.

Upgrade JIRA

3. Stop the cluster

You need to stop JIRA on all nodes in the cluster. We also recommend that you configure your load balancer to redirect the traffic away from JIRA until the upgrade is complete on all nodes.

4. Back up

Back up the following components:

  • JIRA database. You can use the database native tools to create the backup.
  • JIRA installation directory. It's enough if you back up only one of the whole cluster.
  • JIRA shared directory. That's a subdirectory of the home directory that is accessible by all nodes in the cluster.
  • JIRA home directory on each node.

5. Delete the old add-on cache

Delete the old add-on cache on each node in the cluster, so that it doesn't affect the new version. Go to <home-directory>/plugins/on each node, and delete the contents of this directory.

tip/resting Created with Sketch.

For major upgrades, you can delete the whole plugins directory. We've found that upgrading without plugins tends to be faster and more reliable.

6. Upgrade the first node

To upgrade the first node:

  1. Download JIRA Software or JIRA Service Desk Data Center. Choose the tar.gaz or ZIP archive to speed up the process.

    Good to know...

    If you're using both JIRA Software and JIRA Service Desk, upgrade JIRA Software only. You'll later update Service Desk directly in JIRA, without a separate installer.

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

  3. Go to <installation-directory>/bin, and edit the setenv.bat / setenv.sh file. In JIRA_HOME, enter the path to the existing local home directory on that node.

    tip/resting Created with Sketch.

    You'll find the JIRA_HOME parameter at the top of the file. You'll also need to uncomment it.

  4. If you're using a MySQL database, download the latest jdbc driver, and place it in <installation-directory>/lib.
  5. Reapply any customizations, like JVM properties, from the old version to the new one.
  6. Copy the new installation directory. You will later use it as a template to replicate JIRA to other nodes.
  7. Start JIRA. During this step, your database will be upgraded. 
  8. Go to  > Add-ons > Manage add-ons, and upgrade your add-ons to the supported versions.
  9. Rebuild index in JIRA. For more info, see Search indexing. 

7. Copy JIRA to remaining nodes

To replicate JIRA to other nodes:

  1. Copy the installation directory (the template you created before) to the new node.
  2. If the path to the home directory is different on this node, update it in the setenv.bat / setenv.sh file.
  3. Change indexes on the new node:
    1. Go to <home-directory>/caches/indexes, and delete the contents of this directory.
    2. Start JIRA on the new node.
    3. After JIRA is started, verify that the indexes were automatically copied from the first node. If not, you'll need to copy them manually.
  4. Rebuild index in JIRA. For more info, see Search indexing. 

Repeat this process for each remaining node.

8. (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  > Applications > Versions and licenses.
  2. Update JIRA Service Desk. This will automatically update Service Desk to a compatible version.

Troubleshooting

Did something go wrong?

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

If you need to retry the upgrade, you must roll back to your previous setup first. Do not attempt to run an upgrade again, or start the older version of JIRA again after an upgrade has failed. 

Last modified on Sep 5, 2018

Was this helpful?

Yes
No
Provide feedback about this article

Related content

Powered by Confluence and Scroll Viewport.