Upgrading JIRA applications using the installer

In this guide, we'll run you through using the installer to upgrade your JIRA instance to the latest JIRA version on Windows or Linux.

Upgrading to any later version is free if you have current software maintenance. See our Licensing FAQ to find out more.

Before you begin

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

Is installer the right upgrade method for you?

Tell me more...

You can choose to upgrade using the installer, or manually using a zip or tar.gz file. In most cases the installer is the easiest way to upgrade your JIRA instance.

You will need to upgrade manually if:

  • you are moving to a different operating system or database software as part of this upgrade.
  • you are upgrading from JIRA earlier than 4.3


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:

  • The JIRA installer includes Java (JRE) and Tomcat, so you won't need to upgrade these separately.
  • 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. For example, if you are upgrading from 7.1 to 7.3 you should read the upgrade notes for 7.2 and 7.3.

Check some known issues
Tell me more...

Following the upgrade on Linux, you might encounter some problems with certain system text displayed in the application (CAPTCHA and gadgets). Instead of showing regular alphanumeric letters, the text will appear to be garbled and look like symbols. To avoid this problem, you should install several fonts that are required by JIRA. For more info, see JIRA UI shows unreadable text.

Plan your upgrade

1. Determine your upgrade path

Use the tables below to determine the most efficient upgrade path from your current version to the latest versions of JIRA. 

Show JIRA Core (JIRA)...
Your versionRecommended upgrade path
Earlier than 4.4.5Upgrade to 4.4.5, then follow paths below (versions earlier than 4.3.0 will need to be upgraded manually).
4.4.5 to 5.1Upgrade to any version between 5.2/6.4, then follow paths below.
5.2 to 6.4Upgrade to 7.0.11*, then upgrade to any later version.
7.0 or laterUpgrade to any later version of JIRA Core.

*The 7.0 version introduced significant changes that affect your user management, application access, and JIRA installation setup. Consult the Migration hub before upgrading.

Show JIRA Software (JIRA + Agile)...
Your versionRecommended upgrade path
Earlier than 4.4.5Upgrade to 4.4.5, then follow paths below (versions earlier than 4.3.0 will need to be upgraded manually).
4.4.5 to 5.1Upgrade to any version between 5.2/6.4, then follow paths below.
5.2 to 6.4Upgrade to 7.0.11*, then upgrade to any later version.
7.0 or laterUpgrade to any later version of JIRA Software.

*The 7.0 version introduced significant changes that affect your user management, application access, and JIRA installation setup. Consult the Migration hub before upgrading.

Show JIRA Service Desk...
Your versionRecommended upgrade
Earlier than 2.5.xUpgrade to 3.0, then upgrade to the latest version.
3.0Upgrade directly to the latest version.

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

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

4. Back up

  1. Back up your database and confirm the backup was created properly. 
    You can use the database native tools to create the backup. If your database does not support online backups, you'll need to stop JIRA first.
  2. Back up your installation directory and home directory.
    The installation wizard will back up your JIRA directories as part of the installation process, but you should also back these directories up manually before starting the upgrade.

    Where is my home directory?

    You can find the location of your home directory in the <installation-directory>/atlassian-jira/WEB-INF/classes/jira-application.properties file.


    The default paths are:

    Windows: C:\Program Files\Atlassian\Application Data\JIRA

    Linux: /var/atlassian/application-data/jira

5. Download JIRA

Download the installer for your operating system – JIRA Core, JIRA Software, or JIRA Service Desk

Good to know...
  • JIRA Software and JIRA Service Desk already contain the JIRA Core installer.
  • If you're upgrading both JIRA Core/Software and JIRA Service Desk, upgrade JIRA Core/Software only. You'll later update Service Desk directly in JIRA, without a separate installer.

6. Run the installer

  1. Run the installer.

    Show me how to do this in Windows...

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

    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.

    Show me how to do this in Linux...

    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.

    Next, 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 to upgrade JIRA:
    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. Back up these directories is strongly recommended. This will create a .zip backup of the JIRA home and installation directories.
    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.

  3. When JIRA starts for the first time after an upgrade, you'll be presented with an overview of the upgrade. This page will show to the first 10 admins who log in to JIRA post upgrade, and only for 14 days. This overview contains information on critical updates to your JIRA instance, and it also gives you a dynamic overview of your add-ons and application links. You can access this information at any time by selecting  > Latest upgrade report.

  4. There are some additional steps you may need to take if:

    • you use Crowd for user management

      Click here to expand...

      If you are using Crowd for user management, reapply the modifications from the following files from your existing installation directory to the new files. Do not copy the files as they may be different in the new version of JIRA.

      • <Installation-Directory>/atlassian-jira/WEB-INF/classes/crowd.properties
      • <Installation-Directory>/atlassian-jira/WEB-INF/classes/seraph-config.xml

After the upgrade

7. Upgrade the database driver

If you're using a MySQL database, download the latest jdbc driver and place it in <JIRA-installation-directory>/lib

8. Re-apply any 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

All other customizations need to be reapplied manually.

Show me how to do this...

Any other configurations or customizations (including any other modifications in the server.xml file) are not migrated during the upgrade and need to be reapplied manually.

  1. Stop your upgraded JIRA instance.
  2. Reapply the customizations to the relevant files in the upgraded JIRA installation directory.
  3. Restart the upgraded JIRA instance.

We strongly recommend you test your customizations in a test instance prior to upgrading your production instance as changes may have been made to JIRA that make your customizations unusable.

Show me the list of important files...

If you're unsure which files you might have modified, take a look at the list of important files in the JIRA installation directory.

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

10. Upgrade your plugins

Once you have confirmed the availability of compatible versions, you should upgrade your plugins after successfully upgrading JIRA. This can be done via  > Add-ons > Manage add-ons.

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 Nov 28, 2018

Was this helpful?

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