Upgrading JIRA applications manually

In this guide, we'll run you through upgrading JIRA manually, if your installation doesn't support using the installer. Upgrading to any later version is free if you have current software maintenance. See our Licensing FAQ to find out more.

You should use this method to upgrade JIRA if you meet any of the following criteria: 

Before you begin

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

Is manual 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 use JIRA 4.0.0 or later on Solaris
  • you are upgrading from JIRA earlier than 4.3

Note that if you're upgrading only JIRA Service Desk, you'll need to use the installer.

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

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. Create an XML backup of your database.

  2. Back up your installation directory and home directory.

    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

  3. As soon as the backup is complete, delete the <home-directory>/dbconfig.xml file from your existing home directory. This will allow you to connect JIRA to a new database.

5. Download JIRA

Download the zip or tar.gz archive – JIRA Core or JIRA Software.

Good to know...
  • JIRA Software already contains 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. Extract the file and upgrade JIRA

  1. Stop JIRA applications.

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

  3. Edit the  <installation-directory>\atlassian-jira\WEB-INF\classes\jira-application.properties file to point to your existing JIRA home directory. Make sure that you deleted the dbconfig.xml file, otherwise JIRA will try to connect to your existing database. 

  4. Copy your jdbc driver jar file from your existing JIRA installation directory to /lib  in your new installation directory.

  5. 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/osuser.xml (4.3.0 and earlier)

        • <Installation-Directory>/atlassian-jira/WEB-INF/classes/crowd.properties
        • <Installation-Directory>/atlassian-jira/WEB-INF/classes/seraph-config.xml
      • you are upgrading from version 4.3.0 or earlier

        Click here to expand...

        The jira-application.properties file, which you might know from advanced configuration, now contains only the location of your JIRA home directory.

        You should reapply your advanced configuration settings directly in JIRA by going to > System > Advanced Settings.

7. Start JIRA and connect it to the database

  1. Start JIRA to launch the setup wizard. Go to <installation-directory>/bin, and run the start-jira.sh / start-jira.bat file.

  2. Access JIRA through your browser, and choose I'll set it up myself to get access to more setup options.

  3. Select My own database, and provide details of a new, empty database.

  4. Click Import your data, and select the file with your XML backup.

    Avoid passing through a proxy when performing an XML restore, especially if your JIRA instance is very large. Using a proxy may cause timeout errors.
  5. 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.
  6. Take a quick look around your JIRA site to confirm that your projects and issues are present and everything looks normal. You should see the new JIRA version number in the page footer.

After the upgrade

8. Re-apply any modifications

If you have customized JIRA (such as an SSL configuration in the  server.xml  file, or additional memory allocation in the setenv.sh / setenv.bat file ), you'll need to reapply the customizations to the relevant files in the newly upgraded JIRA installation directory.

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.

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 Dec 19, 2018

Was this helpful?

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