Upgrading Jira Data Center (installer)

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

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

Before you begin

Step 1: 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 2: Choose your version

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

Step 3: 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 its installation directory 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 Windows or Linux binary.

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

Step 2. Start the installation wizard

The installation wizard will guide you through the upgrade process.

  1. Run the installer you've downloaded.

    I'm using Windows...

    a) Run the .exe file. We recommend using a Windows administrator account.

    b) If prompted to allow the upgrade wizard to make changes to your computer, choose Yes. If you do not, the installation wizard will have restricted access to your operating system and any subsequent installation options will be limited.

    I'm using Linux...

    a) Change to the directory where you downloaded Jira, then execute this command to make the installer executable:

    $ chmod a+x atlassian-jira-X.X.X-x64.bin

    Where X.X.X is the Jira version you downloaded.

    b) Run the installer – we recommend using sudo to run the installer:

    $ sudo ./atlassian-jira-X.X.X-x64.bin

    You can also choose to run the installer with root user privileges.

  2. Follow the prompts in the wizard:

    1. When prompted, choose Upgrade an existing Jira installation.

    2. Make sure the Existing Jira installation directory suggested by the wizard is correct (especially important if you have multiple Jira installations on the same machine.)

    3. If you have already backed up the Jira home directory, clear the Back up the Jira home directory check box to avoid creating an extra backup. 

    4. The wizard notifies you of customizations in the Jira installation directory. Make a note of these as you'll need to reapply them later. 

      Your current customizations will be overwritten, but you can later copy them from your backups.

  3. In the last screen, the upgrade wizard will ask you to start the Jira instance and complete the upgrade. We recommend that you stop at this step, and complete the remaining steps from this page, up until Start Jira for the first time.

    Starting Jira here won't affect your upgrade in any way, but Jira needs to be shut down to complete the remaining steps. Once you complete them, you can go back to the wizard and start Jira.

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 modifications 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. In this step, you need to re-apply the same modifications to the new 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.

Migrated modifications

During the upgrade, the wizard migrated the following from your existing Jira installation:

  • TCP values in the server.xml file.
  • Location of your Jira home directory in the jira-application.properties file.
  • The following values in the setenv.sh / setenv.bat file:
    • JVM_SUPPORT_RECOMMENDED_ARGS
    • JVM_MINIMUM_MEMORY
    • JVM_MAXIMUM_MEMORY
    • JIRA_MAX_PERM_SIZE 

Other modifications 

Apart from the above, you need to re-apply all other modifications. Here are the most important files: 

  • server.xml
  • dbconfig.xml
  • jira-config.properties
  • setenv.sh / setenv.bat (memory allocation and other JVM arguments)

for more, see Important files in Jira

Pool-max-size

If you're upgrading from Jira 7.x to Jira 8.x we recommend changing the pool-max-size parameter to 40 in your dbconfig.xml before the upgrade. Leaving the default of 20 can sometimes lead to “ResultSet Closed” errors during re-indexing on 8.x. For information on implementing the change, see Tuning database connections.


Step 5. Disable automatic reindex

This step is recommended when upgrading from Jira 7.x to Jira 8.x. If you're already on the 8.x line, you can omit this step.

Because of the changes to indexes that we've introduced in Jira 8.0, the index 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 it. To avoid reindexing twice (after startup and after upgrading your apps), you can disable the automatic reindex, and run the second one later, whenever you’re ready.

  1. Edit or create the following file:

    <jira-home-directory>/jira-config.properties
  2. Add the following line, and save the file:

    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. Go back to your upgrade wizard and complete the upgrade to start Jira.

    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. 

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 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.

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  > Manage apps > Manage apps.
  2. Upgrade your apps to the supported versions.
  3. Once the apps are upgraded, you can enable them.

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  > 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 > System > System info, and scrolling down to the Cluster nodes section.

Well done!

You've upgraded Jira to a new version.

Last modified on May 8, 2020

Was this helpful?

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