Upgrading Jira Data Center (manual)

You've chosen to upgrade Jira Data Center (clustered) manually by using the archive.

Looking for a different upgrade method? See Upgrading Jira applications.

Avoid using this upgrade method if you initially installed Jira using the binary installer (.exe on Windows or .bin on Linux). Upgrading binary installations manually is not supported and is known to cause problems on startup.

Before you begin

Step 1: Locate the Jira home directory to determine the initial installation method

We recommend upgrading Jira using the same method that was used to install it for the first time. If you’re unsure which method that was, find the location of your Jira home directory. That’s usually a good indicator of whether Jira was installed manually or from a binary installer. For more information, see Jira application home directory.

Step 2: Prepare for the upgrade

Make sure you have completed the steps in Preparing for the upgrade. These are mandatory pre-requisites, and are essential for a smooth upgrade.

Step 3: Choose your version

If you need help choosing the right version for you, head to the upgrade matrix to get a quick rundown of features, supported platforms, and technical upgrade notes for all Jira versions.

Step 4: Stop the cluster

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.

Upgrade Jira on the first node

To avoid upgrading each of the nodes separately, you’ll just upgrade one of them, and make it a template. Then, you’ll copy this template to remaining nodes. You can choose any node here.

Step 1. Download Jira

  1. Download one of the Jira applications from our website. Choose the tar.gz or zip archive.

If you're upgrading both Jira Software and Jira Service Management, upgrade Jira Software only. You'll later upgrade Jira Service Management directly in Jira, without a separate installer.

Step 2. Extract the files

Extract the archive you've downloaded, and start the upgrade.

  1. Extract (unzip) the files to a directory (this is your new installation directory, and must be different to your existing installation directory). 
  2. Point Jira to your existing Jira home directory.

    We recommend that you do it by setting the JIRA_HOME environment variable. For more info on how to do this, see Setting Jira home directory.

Step 3. Install the database driver

If you're using an Oracle or MySQL database, download a new JDBC driver. For other databases, you can omit this step.

tip/resting Created with Sketch.

If the driver is up to date, you can also copy it from your previous version.


  1. Download one of the following drivers:

  2. Place it in <installation-directory>/lib.

Step 4: Re-apply any custom changes and increase pool-max-size

While using Jira, you’ve probably added some custom modifications to Jira files. These may include connection details, settings related to memory allocation, or other JVM arguments. Usually, these are the files that contain custom changes: 

  • server.xml
  • dbconfig.xml
  • jira-config.properties
  • web.xml

For more information, see Important files in Jira.

In addition to these files, if your Jira is running over SSL, you need to reimport certificates into the trust store. For details on how to do this, see How to import a public SSL certificate into a JVM.

You need to re-apply your custom changes to your respective new Jira files by copying them from your backups.

Make sure you don't just copy over the old files, as the 'native' settings they contain might have changed between the Jira versions.

We'll make another check on Jira startup and will show you all the files you might have skipped that still contain changes that have not been copied over. Then you'll be able to click to automatically copy the changes over.

Note that the check will only be run on the following configuration files:

- <jira-home-directory>/atlassian-jira/ directory
- <jira-home-directory>/conf/server.xml
- <jira-home-directory>/bin/setenv.sh

and the automatic transfer will only be supported for ATST plugin 1.20.0 and later.

To automatically transfer the changes, the installer copy of the modified file needs to be the same as in the version you're upgrading to.

tip/resting Created with Sketch.

Tomcat started to use double-quotes as of version 8.5.48 as a result of Expansion of JAVA_OPTS in catalina.sh containing '*' stops startup on linux bug. That's why when you upgrade and set parameters in setenv.sh or setenv.bat, make sure that you:

  • Don't remove the double-quotes in the catalina.sh
  • Set all your parameters in one line without any new line in setenv.sh or setenv.bat

Otherwise you might experience issues starting up Jira. 


Pool-max-size

If you’re upgrading from Jira 7.x to the next platform version, such as 8.x or 9.x, we recommend that you change the pool-max-size parameter to 40 in your dbconfig.xml before the upgrade. Leaving the default value of 20 can cause various issues related to database connection. For information on implementing the change, see Tuning database connections.


Step 5. Disable automatic reindex

This step is recommended when upgrading between platform versions. For example, when you’re switching from Jira 7.x to 9.x or from Jira 7.x to 8.x.

If you're already upgrading between Jira feature releases (for example, from 8.13 to 8.20, etc.), you can omit this step.

Because of the indexing changes introduced between 8.x and 9.x Jira platform versions, indexes from any earlier Jira version will be incompatible after the upgrade.
To create a new index, Jira will trigger an automatic reindex right after you start the application. To avoid reindexing twice (after startup and after upgrading your apps), you can disable the automatic reindex and then run the second one later, whenever you’re ready.

To disable automatic reindex:

  1. Edit or create (if it doesn’t exist) the following file:

    <jira-home-directory>/jira-config.properties
  2. Add the following line to the preceding file and then save your changes:

    upgrade.reindex.allowed=false


Post-upgrade steps on the first node

Complete these post-upgrade steps only on the first node (the one you've just upgraded). The remaining nodes will later download the upgraded apps and index from the shared directory.

Step 1. Start Jira for the first time

Start your new Jira version, and connect it to the database.

  1. (Installer) Go back to your upgrade wizard and  start Jira.

    (Installer and Manual) You can also start Jira by going to <installation-directory>/bin, and running one of the following files:

    • Windows:  start-jira.bat
    • Linux:  start-jira.sh 

  2. Open Jira in your browser.

  3. Follow instructions on the screen to complete the setup. 
  4. If you've missed any file with custom changes that have not been copied over, you can automatically copy the changes over now. 

    Note that the check for file changes is only be run on the following configuration files:

    - atlassian-jira/ directory
    - conf/server.xml
    - bin/setenv.sh

    and the automatic transfer is only be supported for ATST plugin 1.20.0 and later.

    To automatically transfer the changes, the installer copy of the modified file needs to be the same as in the version you're upgrading to.

    After the changes have been copied over, you'll be prompted to restart Jira.

Post-upgrade landing page

After a successful upgrade, you should see the post-upgrade landing page. It has some useful information about the new version, as shown below.

  1. Need to know: A list of new features that might affect your work as an admin.
  2. User apps: Status of your apps after the upgrade.
  3. Application links: Status of your application links.
  4. Release notes: Link to release notes where you can see more detailed information about the version you've upgraded to.

Step 2. (Optional) Update Jira Service Management

If you're using Jira Service Management, you can update it directly in the UI, without downloading a separate installer.

  1. Go to Administration (> Applications > Versions and licenses.
  2. Update Jira Service Management. This will automatically update Jira Service Management to a compatible version.

Step 3. Upgrade apps (add-ons)

Now you can upgrade apps that had the Compatible once both are updated status. If you need more information about the statuses and apps in general, see Preparing for the upgrade.

  1. Go to Administration (> Manage apps > Manage apps.
  2. Upgrade your apps to the supported versions.
  3. Once the apps are upgraded, you can enable them.

Upgrading apps in a DC cluster

When upgrading apps, each node will pull the the most recently modified app jar file from the shared home on reboot.

To determine the file version, Jira uses the  <version> value inside atlassian-plugin.xml. If there are multiple <version> values, Jira uses java.lang.String#compareTo to compare the different values.


Step 4. Rebuild index

Reindex Jira to recreate your index. This step might take some time, depending on how many issues and apps you have.

  1. Go to Administration (> Indexing, and run Lock Jira and rebuild reindex.

Step 5. Copy the upgraded Jira as a template

In this step, you'll copy the new installation directory with all the modifications you did so far. This will give you a template that you'll later copy to other nodes.

  1. Copy the new installation directory to some other location. This will be your template.


Upgrade remaining nodes

By now, you should have the ready Jira template, and upgraded add-ons and index data available in the shared directory. In this step, you'll copy the template to other nodes and start them one by one.

  1. Copy the template installation directory to the new node.

  2. If the path to the local home directory is different on this node, update it in the setenv.bat / setenv.sh file.

  3. Start Jira on this node.

  4. Rinse & repeat: Repeat these steps on the next node.
tip/resting Created with Sketch.

Joining the cluster

You can check if the upgraded nodes are joining the cluster by going to Administration () > System > System info, and scrolling down to the Cluster nodes section.

Well done!

You've upgraded Jira to a new version.

Last modified on Apr 25, 2022

Was this helpful?

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