Upgrading JIRA Using a Rapid Upgrade Method

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 Production Releases. 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. Refer to Important Version-Specific Upgrade Notes for quick links to these guides.
• 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 6.1. The End of Support Announcements for JIRA 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.

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 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 4.4 and later. See JIRA 4.4 Upgrade Notes for details.
• TCP port values in your existing JIRA installation's server.xml file. Other configurations or customizations in this file are not migrated.
• Custom values in your existing JIRA installation's jira-application.properties and setenv.sh / setenv.bat files.
  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

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 Installation Directory, which had been deleted, added or modified from a 'default' JIRA installation. If you have made customizations to your seraph-config.xml file or any other file customizations in your JIRA installation directory which are not handled by the upgrade wizard, you must migrate these to the upgraded JIRA installation manually.

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

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, 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 installation. If your attachments and index files are located outside your JIRA Home Directory, you must manually back up these files. These pages describe how to find out where these directories are located in your environment: 
  • Your attachments directory — Refer to the Configuring File Attachments page for your version of JIRA.
  • Your index directory — Refer to the Search Indexing page for your version of JIRA. 

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 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 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 data (to ensure structural consistency of your database backup) by temporarily restricting access to JIRA. Refer to the Preventing users from accessing JIRA during backups page for more information.
  3. Use your database's native backup tools to perform an "offline backup" of your JIRA 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.
• JIRA's 'internal' database is HSQLDB, which should be used for evaluating JIRA only. If you happen to accidentally use the HSQLDB database for a production system, quit the upgrade wizard when it prompts you about the backup and use the Migrating JIRA to Another Server procedure to upgrade JIRA.

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 version to this restored database.

3. Performing the Upgrade

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

• Windows
• Linux

Upgrading JIRA on Windows

1. Download the 'JIRA Windows Installer' (.exe) file (for the new version of JIRA) from the JIRA Download page.
2. Shut down JIRA.
3. Run the '.exe' file to start the upgrade wizard.
   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 Installation Directory of your JIRA installation to be upgraded.
   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.
      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. One relatively common customization that the upgrade wizard cannot automatically migrate is an SSL configuration defined in the conf/server.xml file of the JIRA Installation Directory.
   2. At the 'Upgrade Check List' step, back up your external database and check that any non-bundled plugins will be compatible with your upgraded JIRA version. 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. Start your new (upgraded) JIRA installation.
         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 Installation Directory.
         3. Restart the upgraded JIRA installation.
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.
   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.
   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.
      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. One relatively common customization that the upgrade wizard cannot automatically migrate is an SSL configuration defined in the conf/server.xml file of the JIRA Installation Directory.
   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.
         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 Installation Directory.
         3. Restart the upgraded JIRA installation.
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 the Plugin Repository in your Administration Console.

Congratulations! You have completed your JIRA upgrade.