Upgrading Jira (installer)
You've chosen to upgrade Jira Server or Data Center (non-clustered) by using the installer.
Looking for a different upgrade method? See Upgrading Jira applications.
Avoid using this upgrade method if you initially installed Jira manually from a
.zip archive. Upgrading manual installations using the binary installer is not supported and is known to cause problems on startup.
Before you begin
Locate the Jira home directory to determine the initial installation method
We recommend upgrading Jira using the same method that was used to install it for the first time. If you’re unsure which method that was, find the location of your Jira home directory. That’s usually a good indicator of whether Jira was installed manually or from a binary installer. For more information, see Jira application home directory.
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.
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.
- Download one of the Jira applications from our website. Choose the Windows or Linux installer.
If you're upgrading both Jira Core/Software and Jira Service Management, upgrade Jira Core/Software only. You'll later upgrade Jira Service Management directly in Jira, without a separate installer.
Start the installation wizard
The installation wizard will guide you through the upgrade process.
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
X.X.Xis the Jira version you downloaded.
b) Run the installer – we recommend using
sudoto run the installer:
$ sudo ./atlassian-jira-X.X.X-x64.bin
You can also choose to run the installer with root user privileges.
- Follow the prompts in the wizard:
- When prompted, choose Upgrade an existing Jira installation.
- 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.)
- 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.
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.
- When prompted, choose Upgrade an existing Jira installation.
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.
(Optional) If you use Crowd for user management, complete these extra steps: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.
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.
If the driver is up to date, you can also copy it from your previous version.
Step 4: Re-apply any custom changes 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.
During the upgrade, the wizard migrated the following from your existing Jira installation:
- TCP values in the
- Location of your Jira home directory in the
- The following values in the
Apart from the above, you need to re-apply all other modifications. Here are the most important files:
setenv.bat(memory allocation and other JVM arguments)
For more information, see Important files in Jira.
In addition to these files, if your Jira is running over SSL, you need to reimport certificates into the trust store. Don't forget to move this from your backup to the appropriate location as noted in tomcat.xml if necessary.
For details, see How to import a public SSL certificate into a JVM.
You need to re-apply your custom changes to your respective new Jira 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.
We'll make another check on Jira startup and will show you all the files you might have skipped that still contain changes that have not been copied over. Then you'll be able to click to automatically copy the changes over.
Note that the check will only be run on the following configuration files:
- <jira-home-directory>/atlassian-jira/ directory
and the automatic transfer will only be supported for ATST plugin 1.20.0 and later.
To automatically transfer the changes, the installer copy of the modified file needs to be the same as in the version you're upgrading to.
Tomcat started to use double-quotes as of version 8.5.48 as a result of Expansion of JAVA_OPTS in catalina.sh containing '*' stops startup on linux bug. That's why when you upgrade and set parameters in setenv.sh or setenv.bat, make sure that you:
- Don't remove the double-quotes in the catalina.sh
- Set all your parameters in one line without any new line in setenv.sh or setenv.bat
Otherwise you might experience issues starting up Jira.
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.
Disable automatic reindex
This step is recommended for the platform upgrade, that is when upgrading from 7.x to 8.x.
Because of the changes to indexes that we've introduced in Jira 8.0, your old index is incompatible with the new version. To create a new one, 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.
Edit or create the following file:
Add the following line, and save the file:
Start Jira for the first time
Start your new Jira version.
- 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:
- Open Jira in your browser.
If you've missed any file with custom changes that have not been copied over, you can automatically copy the changes over now.
Note that the check for file changes is only be run on the following configuration files:
- atlassian-jira/ directory
and the automatic transfer is only be supported for ATST plugin 1.20.0 and later.To automatically transfer the changes, the installer copy of the modified file needs to be the same as in the version you're upgrading to.
After the changes have been copied over, you'll be prompted to restart Jira.
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.
- Need to know: A list of new features that might affect your work as an admin.
- User apps: Status of your apps after the upgrade.
- Application links: Status of your application links.
- Release notes: Link to release notes where you can see more detailed information about the version you've upgraded to.
Your Jira instance has been upgraded. Below you can learn how to upgrade Jira Service Management, if you have it, and how to upgrade your apps.
(Optional) Update Jira Service Management
If you're using Jira Service Management, you can update it directly in the UI, without downloading a separate installer.
- Go to Administration ( ) > Applications > Versions and licenses.
- Update Jira Service Management. This will automatically update Jira Service Management to a compatible version.
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.
- Go to Administration ( ) > Manage apps > Manage apps.
- Upgrade your apps to the supported versions.
- Once the apps are upgraded, you can enable them.
Since your old index is incompatible, reindex Jira to rebuild it. This step might take some time, depending on how many issues and apps you have.
- Go to Administration ( ) > Indexing, and run Full re-index.
You've upgraded Jira to a new version.