Upgrading JIRA applications using a rapid upgrade method

If you're upgrading from a version of JIRA earlier than 7.0, you should consult the Migration hub. The release of JIRA 7.0 contained functionality that affects your user management, application access and log in permissions, and your JIRA installations setup, and it's very important that you understand the requirements and the implications before you upgrade. The Migration hub has all this information in one handy space.

This page describes how to upgrade the JIRA platform version 4.3.0 or later in the quickest way possible. This method can save you time since it does not require you to set up a separate test instance before you upgrade (that is, you upgrade JIRA applications "in-place"). However, it does assume that your JIRA applications are not mission critical and that users or the business won't be negatively affected when JIRA applications are unavailable during the upgrade.

You should use this method to upgrade JIRA applications if you are upgrading from the JIRA platform version 4.3.0 or later on Windows or Linux. See Upgrading JIRA applications for more information on the methods you can use to upgrade JIRA applications.

On this page:

Before you start

  • Read about the new version - Review the release notes and upgrade notes for the version of JIRA that you are upgrading to. See our Release notes for JIRA Server. If you plan to skip a few JIRA versions during your upgrade, we strongly recommend that you read the upgrade guides for all major versions between your current version and the version to which you are upgrading.
  • Check your license - Verify that your license support period is still valid.
  • Check for known issues - Use the JIRA Knowledge Base to search for any issues in the new version that will affect you.
  • Check for compatibility:
    • Confirm that your operating system, database, other applicable platforms and hardware still comply with the requirements for JIRA 7.3. The End of Support Announcements page also has important information regarding platform support for future versions of JIRA.
    • If you have installed JIRA plugins (i.e. not included with JIRA), verify that they will be compatible with the version of JIRA you are upgrading to. You can find a plugin's compatibility information from the plugin's home page on the Atlassian Plugin Exchange.
    • Some anti-virus or other Internet security tools may interfere with the JIRA upgrade process and prevent the process from completing successfully. If you experience or anticipate experiencing such an issue with your anti-virus/Internet security tool, disable this tool before proceeding with the JIRA upgrade.
  • Prestaging and testing your new version of JIRAWe strongly recommend performing your upgrade in a test environment first. Do not upgrade your production JIRA server until you are satisfied that your test environment upgrade has been successful.
    • If you have any problems with your test environment upgrade which you cannot resolve, create an issue at our support site so that we can assist you.
    • If you have any problems during the upgrade of your production JIRA server, do not allow your users to start using this server. Instead:
      • Continue to use your old JIRA server — this will help ensure that you do not lose production data.
      • Also create an issue at our support site so that we can help you resolve the problems with your upgrade.
        Instructions for prestaging and testing
      1. If you want to use a copy of your production data when you test the upgraded JIRA system, make a copy of your production database using your native database backup tools. See Backing up data. You can alternatively skip this step and use a new database for testing.
      2. Install the version of JIRA you want to upgrade to onto a system you can use for testing (use either a test server or a separate directory on an exisitng system). This will become your new production system after you complete the upgrade process. Follow the instructions here to install a new version of JIRA: Installing JIRA applications.

      3. Migrate any customizations you use in your production system. Follow the instructions in step 3.4 (Migrate your existing JIRA configurations over to your new JIRA installation) in the "Migrating JIRA to another server" page.
      4. Connect the new version of JIRA to the copy of the production database (not the existing production database) or a new testing database. See Connecting JIRA to a database.
      5. Start the new version of JIRA. See this Knowledge Base article about how to test mail settings without accidentally sending notifications to users from the test system: How to Prepare a Development Server's Mail Configuration.
      6. Install any plugins that you use in your existing production version of JIRA. Some plugins have different compatibility for different JIRA vesions, so this step will ensure that your plugins are updated for this new JIRA version.
      7. Re-index JIRA so the new plugin information is captured in the index.
      8. Check out the features and functionality you use in the new version to understand how they behave and how any changes will impact your team. It can be very helpful to have a group of users look at the new system and carry out their usual tasks to make sure they won't run into any issues when the new version is in production.
        When you are ready to begin the process of migrating your production data to this new version, shut down JIRA (for example, by executing either the /bin/stop-jira.sh or \bin\stop-jira.bat file in your JIRA application installation directory, or by stopping the JIRA service).

 

1. Checking for customizations

Using the rapid upgrade method allows the installer to automatically perform many of the upgrade tasks for you. However, if you have made customizations to your JIRA application installation, you must migrate customized files manually to the upgraded installation. The installer checks for and migrates automatically:

  • Legacy database configurations defined as a datasource within the application server (used in JIRA 4.3.x and earlier) to the new database configuration used in JIRA platform version 4.4 and later. See JIRA 4.4 Upgrade Notes for details.
  • TCP port values in your existing JIRA application installation's server.xml file. Other configurations or customizations in this file are not migrated.
  • Custom values in your existing JIRA application installation's jira-application.properties and setenv.sh / setenv.bat files.
    (info) In the setenv.sh / setenv.bat file, only the following values are migrated:
    • JVM_SUPPORT_RECOMMENDED_ARGS
    • JVM_MINIMUM_MEMORY
    • JVM_MAXIMUM_MEMORY
    • JIRA_MAX_PERM_SIZE
  • If JIRA is running as a service on Windows, the Java startup options configured for the service (as described in Setting properties and options on startup - Windows service) will be reset to the defaults. If you've changed memory allocation settings or added any non-default parameters, make sure to save that information before proceeding with the upgrade. If not manually saved, these settings will be lost.

During the upgrade process, the installer detects and notifies you of any files (other than jira-application.properties and setenv.sh / setenv.bat) in the atlassian-jira subdirectory of your existing JIRA application installation directory, which had been deleted, added or modified from a 'default' JIRA application installation. If you have made customizations to your seraph-config.xml file or any other file customizations in your JIRA application installation directory which are not handled by the upgrade wizard, you must migrate these to the upgraded JIRA application installation manually.

The upgrade feature also re-uses your existing JIRA application home directory so that any key data stored in this directory from your previous JIRA application installation will be retained after the JIRA application upgrade.

(info) Please Note:

  • The upgrade process requests that you conduct a backup of your database using your database's backup utilities. If your database does not support online backups, you can stop the upgrade process, shut down JIRA applications, perform your database backup and then restart the upgrade process to continue on.
  • The installer automatically backs up the installation and home directories of the existing JIRA application installation. If your attachments and index files are located outside your JIRA application home directory, you must manually back up these files. These pages describe how to find out where these directories are located in your environment: 

2. Backing up your external database

After you launch the upgrade wizard, but before it begins the upgrade, it asks you to back up your external database. You can back up the database using your database's native backup tools, however, note the following:

  • If your database's native backup tools support online backups (i.e. backups that would typically create a "snapshot" of your JIRA application database while the database is still in use), you can leave the upgrade wizard running while you perform the database backup and then continue on with the wizard after verifying that the database backup was created correctly.
  • If your database's native backup tools do not allow you to perform an online backup of your JIRA application database, you should:
    1. Quit the upgrade wizard when it prompts you to back up the database.
    2. Prevent users from updating your existing JIRA application data (to ensure structural consistency of your database backup) by temporarily restricting access to JIRA applications. Refer to the Preventing users from accessing JIRA applications during backups page for more information.
    3. Use your database's native backup tools to perform an "offline backup" of your JIRA application database and verify that this backup was created correctly.
    4. Re-start the Linux / Windows Installer to start the upgrade wizard again and continue from where you left off.
  • The JIRA application 'internal' database is H2, which should be used for evaluating JIRA applications only. If you happen to accidentally use the H2 database for a production system, quit the upgrade wizard when it prompts you about the backup and use the Migrating JIRA applications to another server procedure to upgrade your JIRA applications.

(warning) Inconsistent database backups may not restore correctly! If you are unfamiliar with your database's native backup/restore facilities, then before proceeding, test your database backup's integrity by:

  • restoring the database backup to a different (test) system, and
  • connecting a test instance of your current JIRA application version to this restored database.

3. Performing the upgrade

Refer to the appropriate upgrade instructions below for your operating system:

Upgrading JIRA applications on Windows

  1. Download the 'JIRA Windows Installer' (.exe) file (for the new JIRA application version) from the JIRA applications download page.
  2. Shut down your JIRA applications.
  3. Run the '.exe' file to start the upgrade wizard.
    (info) If a Windows 7 (or Vista) 'User Account Control' dialog box asks you to allow the upgrade wizard to make changes to your computer, specify Yes. If you do not, the installation wizard will have restricted access to your operating system and any subsequent installation options will be limited.
  4. At the 'Upgrading JIRA?' step, choose the Upgrade an existing JIRA installation option.
  5. In the Existing JIRA installation directory field, specify the JIRA application installation directory of your JIRA installation to be upgraded.
    (info) The upgrade wizard will attempt to find an existing JIRA installation and use its location to pre-populate this field. However, always verify this location, particularly if you have multiple JIRA installations running on the same machine.
  6. During subsequent steps of the upgrade wizard, you will be prompted to specify or do the following options:
    1. At the 'Back up JIRA directories' step, ensure the Back up these directories option is selected. This creates 'zip' archive file backups of your existing JIRA installation and JIRA home directories in their respective parent directory locations.
      (info) Please Note:
      • Choosing this option is strongly recommended!
      • At this point, the upgrade wizard notes any customizations in your existing JIRA installation directory which it cannot automatically migrate to your upgraded JIRA installation. If you are informed of any files containing such customizations, please make a note of these files as you will need to manually migrate their customizations (which are not mentioned in the overview above) to your upgraded JIRA installation.

        SSL configuration

        - The upgrade wizard cannot automatically migrate the SSL configuration defined in the conf/server.xml file of the JIRA installation directory.

         

        - If you're using the bundled JRE for JIRA (located in the JRE folder of the JIRA installation directory), then the upgrade wizard cannot import the SSL certs into the new JRE after the upgrade as well. You will need to import the SSL certs into the new JRE. For more information on importing SSL certs, see Running JIRA applications over SSL or HTTPS.

         

        - If you're using the system JRE, you won't have to import the SSL certs into the new JRE after the upgrade, since the JRE would already have the SSL certs after the upgrade. You just need to ensure that JIRA is using the system JRE. To do this, you will need to perform the changes in catalina.bat, as discussed in How to Use System JRE Instead of Embedded JRE.

         

         

  7. At the last step of the upgrade wizard, select the option to launch the upgraded JIRA installation in a browser so you can check the upgrade.

Congratulations, you have completed upgrading your JIRA installation on Windows!

Upgrading JIRA on Linux

  1. Download the appropriate 'JIRA 'Linux 64-bit / 32-bit Installer' (.bin) file that suits your operating system (for the new version of JIRA) from the JIRA Download page.
  2. Shut down JIRA.
  3. Open a Linux console and change directory (cd) to the '.bin' file's directory.
    (warning) If the '.bin' file is not executable after downloading it, make it executable, for example:
    chmod a+x atlassian-jira-X.Y.bin
    (where X.Y represents your version of JIRA)
  4. Execute the '.bin' file to start the upgrade wizard.
  5. When prompted to choose between creating a new JIRA installation or upgrading an existing installation, choose the Upgrade an existing JIRA installation option.
  6. Specify the JIRA installation directory of your JIRA installation to be upgraded.
    (info) The upgrade wizard will attempt to find an existing JIRA installation and will provide its location as a choice. However, always verify this location, particularly if you have multiple JIRA installations running on the same machine.
  7. During subsequent steps of the upgrade wizard, you will be prompted to specify or do the following options:
    1. Choose the option to back up JIRA's directories. This creates 'zip' archive file backups of your existing JIRA installation and JIRA home directories in their respective parent directory locations.
      (info) Please Note:
      • Choosing this option is strongly recommended!
      • At this point, the upgrade wizard notes any customizations in your existing JIRA installation directory which it cannot automatically migrate to your upgraded JIRA installation. If you are informed of any files containing such customizations, please make a note of these files as you will need to manually migrate their customizations (which are not mentioned in the overview above) to your upgraded JIRA installation.

        SSL configuration

        - The upgrade wizard cannot automatically migrate the SSL configuration defined in the conf/server.xml file of the JIRA installation directory.

         

        - If you're using the bundled JRE for JIRA (located in the JRE folder of the JIRA installation directory), then the upgrade wizard cannot import the SSL certs into the new JRE after the upgrade as well. You will need to import the SSL certs into the new JRE. For more information on importing SSL certs, see Running JIRA applications over SSL or HTTPS.

         

        - If you're using the system JRE, you won't have to import the SSL certs into the new JRE after the upgrade, since the JRE would already have the SSL certs after the upgrade. You just need to ensure that JIRA is using the system JRE. To do this, you will need to perform the changes in catalina.sh, as discussed in How to Use System JRE Instead of Embedded JRE.

         

         

    2. At the 'Upgrade Check List' step, back up your external database. You may have already backed up your database (in step 2 Backing up your external database).
    3. After the 'Upgrade Check List' step, the existing JIRA installation will be shut down if it is still running. The upgrade wizard will then:
      1. Back up your existing JIRA installation.
      2. Delete the contents of the existing JIRA installation directory.
      3. Install the new version of JIRA to the existing JIRA installation directory.
      4. Starts your new (upgraded) JIRA installation.
        (warning) If you noted any files that contain customizations which must be migrated manually to your upgraded JIRA installation (above), then:
        1. Stop the upgraded JIRA installation.
        2. Migrate the customizations from these files into the upgraded JIRA application installation directory.
        3. Restart the upgraded JIRA installation.

            Instructions to migrate existing configurations

          If you have modified properties in configuration files of your existing JIRA installation, make the same modifications in your new JIRA installation. However, because the properties in the configuration files may have changed between versions, you cannot simply copy the configuration files from your existing installation and replace the equivalent files in the new installation.

          For each file you have modified in your existing JIRA installation, you need to manually edit each equivalent file in your new JIRA installation and re-apply your modifications. If a file is not present in your new JIRA installation (for example, osuser.xml in recent JIRA versions), then simply copy that file over to your new JIRA installation.

          The table below lists the most commonly modified files and their locations within your JIRA Installation Directory:

          File

          Location in 'recommended' (formerly 'Standalone') JIRA distributions

          Description

          jira-application.properties

          atlassian-jira/WEB-INF/classes

          Location of the JIRA Home Directory and Advanced JIRA Configuration in JIRA 4.3.x and earlier.

          Any custom property values defined in the jira-application.properties file of your existing JIRA 4.3.x (or earlier) installation must be migrated across to the jira-application.properties file of your new JIRA 7.3 installation before you start your new JIRA installation.

          Upon starting your new JIRA installation, any custom property values in the jira-application.properties file will automatically be migrated across to either the JIRA database or jira-config.properties file. jira.home is the only property of the jira-application.properties file subsequently used by JIRA.

          setenv.bat (Windows) or setenv.sh (Linux)

          bin

          Increasing JIRA Memory

          osuser.xml
          (not required if upgrading from JIRA 4.3.0 or later)

          atlassian-jira/WEB-INF/classes

          Modified if you have integrated LDAP with JIRA, integrated Crowd with JIRA, or if you are using a custom form of external user management or user authentication.

          seraph-config.xml

          atlassian-jira/WEB-INF/classes

          Modified if you have integrated Crowd with JIRA.

          server.xml

          conf

          Modified in the following situations:

          (tick) The version-specific upgrade notes contain details on properties which may have changed in these commonly modified files.

          In addition to the files above, you should also consider and/or perform the following configurations as part of the upgrade process:

          • Using JIRA with Atlassian's Crowd? — If you are using Crowd with JIRA, configure your new JIRA to talk to Crowd as described in Integrating Crowd with JIRA.
            • Remember to configure Crowd to grant JIRA's new hostname/IP access.
          • Allocating additional memory to JIRA — If you had previously allocated additional memory to JIRA, do the same for your new JIRA instance. For more information refer to Increasing JIRA memory.
          • Plugins — For any plugins that you had installed in your old JIRA, download the plugin version for your new version of JIRA from the http://plugins.atlassian.com site.
          • Character encoding — Ensure that character encoding (i.e. locale) is the same on the new and old locations. Your new version of JIRA may not function correctly if attachments are moved between two system with incompatible encoding.
          • Customizations — If you had made any customizations (code, templates or configuration files), copy over compatible versions of these changes to the new JIRA. (The developers within your organization who made the customizations to your old version will need to build and test equivalent changes for the new version, and provide you with the files to copy to your upgraded JIRA installation.)
          • (Optional) Running JIRA on a different port — If your new JIRA is installed on the same machine as your old JIRA, you may wish to make sure it runs on a different port (in case you ever need to restart your old JIRA). See Changing JIRA's TCP ports for details.

  8. The last step of the upgrade wizard provides you with a link to launch the upgraded JIRA installation in a browser, so you can check the upgrade.

Congratulations, you have completed upgrading your JIRA installation on Linux!

4. Post upgrade checks and tasks

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. If JIRA is running as a service in Windows, remember to update your Java settings to match your previous configuration.

Congratulations! You have completed your JIRA upgrade.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport