Upgrading Jira Data Center to 9.4

After you’ve completed the pre-upgrade steps and planned the downtime, proceed with the upgrade from your Jira 8.x or 9.x version to Jira 9.4.

[Unit] 
Description=Atlassian Jira
After=network.target

[Service] 
Type=forking
User=jira
PIDFile=/opt/atlassian/jira/work/catalina.pid
ExecStart=/opt/atlassian/jira/bin/start-jira.sh
ExecStop=/opt/atlassian/jira/bin/stop-jira.sh

[Install] 
WantedBy=multi-user.target

Checking the custom configuration file list

If you've made custom changes to other files, you should transfer them manually. Such customization may include connection details, settings related to memory allocation, or other JVM arguments. Most often, the following files are modified:

• server.xml
• dbconfig.xml
• jira-config.properties
• web.xml
• setenv.sh / setenv.bat (memory allocation and other JVM arguments)

Learn more in Important files in Jira

In addition to these files, if your Jira is running over SSL, you should reimport certificates to the trust store. For details on how to do this, see How to import a public SSL certificate into a JVM.

If you're on the latest version of the ASTS plugin, you can see the list of files with custom changes. To do this, go to Administration > Applications > Plan your upgrade.

Stopping the cluster

Stop Jira on all nodes in the cluster. We also recommend that you configure your load balancer to redirect the traffic away from Jira until the upgrade is complete on all nodes.

Upgrade Jira on the first node

To avoid upgrading each of the nodes separately, upgrade one of them and use it as a template. Then, copy the template to the remaining nodes. You can choose any node.

Step 1. Download Jira

Download Jira applications from the Atlassian website.

• Jira Software
• Jira Service Management 

Learn more about upgrade methods

Step 2. Extract the files

Extract the downloaded archive.

1. Extract the files to a new installation directory. It must be different from the existing directory. 
2. Point Jira to the existing Jira home directory.

Step 3. Install the database driver

If you're using the Oracle or MySQL database, download a new JDBC driver (Java Database Connectivity driver). For other databases, skip this step. For more information on supported drivers, see Supported platforms.

If the driver is up to date, you can also copy it from the previous version.

1. Download one of the following drivers:
   1. Oracle: JDBC driver 19.3 (ojdbc8)
   2. MySQL: MySQL Connector/J 5.1 driver
2. Locate the drivers in <installation-directory>/lib.

Step 4: Re-apply any custom changes and increase pool-max-size and the maximum number of open files

While using Jira, you’ve probably customized some Jira files. Such customization may include connection details, settings related to memory allocation, or other JVM arguments. Most often, the following files are modified:

• server.xml
• dbconfig.xml
• web.xml
• jira-config.properties
• setenv.sh / setenv.bat (memory allocation and other JVM arguments)

Make sure you’re copying the changes but not the entire files. Learn more in Important files in Jira

In addition to these files, if your Jira is running over SSL, you should reimport certificates to the trust store. For details on how to do this, see How to import a public SSL certificate into a JVM.

Pool-max-size

Before upgrading from Jira 8.x to Jira 9.x, we recommend checking if the pool-max-size parameter in the dbconfig.xml file is at least 40.

(Linux Server only) Increasing the maximum number of open files

For Linux installations, we recommend that you increase the maximum number of open files. To do this, add the following line to the <jira-install>/bin/setenv.sh file:

ulimit -n 16384

Step 5. Disable automatic reindex

After upgrading from Jira 8.x to Jira 9.4, Jira will trigger an automatic reindex during startup. At this point, your apps from Jira 8.x may not be compatible with version 9.4 yet. So, you should upgrade the apps and make them compatible with Jira 9.4 before you can use Jira.

After finishing the apps upgrade, you’ll need to trigger a manual full reindex to create a new index based on compatible apps' data. This will be the second reindex.

To minimize downtime, you can disable the automatic reindex so that it doesn’t occur twice. You can run the reindex later manually.

To disable the automatic reindex:

1. Edit or create the file <jira-home-directory>/jira-config.properties.
2. Add the following line: upgrade.reindex.allowed=false.
3. Save the file.

Adding the JVM flags to bypass the automatic full reindex for the upgrade from Jira 9.x

Jira 8.x allowed startup without an index with the jira-config.properties entry of upgrade.reindex.allowed=false.

In Jira 9.x, this configuration only works for the first-ever startup — the one that's running or had run the database update tasks. If the node's restarted for any reason, Jira 9.x will understand that it's no longer an upgrade startup and will enforce a full reindex upon startup.

To guarantee that Jira 9.x won't kick off a full reindex in subsequent restarts during the upgrade maintenance window, the following two flags must be added to the JVM startup parameters before you start Jira 9.4 for the first time:

-Dcom.atlassian.jira.startup.allow.full.reindex=false 
-Dcom.atlassian.jira.startup.rebuild.local.index=false

You can add them to JVM_SUPPORT_RECOMMENDED_ARGS in the setenv.sh/setenv.bat file (appended to other parameters you may have there, separated by space characters):

JVM_SUPPORT_RECOMMENDED_ARGS="-Dcom.atlassian.jira.startup.allow.full.reindex=false -Dcom.atlassian.jira.startup.rebuild.local.index=false"

Read Setting properties and options on startup for an overview on setting JVM flags.

The two flags will trigger this dismissible startup screen:

Once the upgrade is over, you should remove the flags so that Jira 9.4 behaves as expected on all subsequent restarts, optimizing index acquisition and delta catch-up with multiple threads. Nodes will rely on their local indexes and fallback to the shared-home snapshots when needed.

For more details on the index startup strategy in Jira 9.0 and 9.4, check Index startup procedure in Jira 9.4 and later.

Post-upgrade steps on the first node

Complete these post-upgrade steps only on the first node—the one you've just upgraded. The remaining nodes will later download the upgraded apps and index from the shared directory.

Step 1. Start Jira

To start the new Jira version:

1. Go to <installation-directory>/bin and run one of the following files:
   1. Windows:  start-jira.bat
   2. Linux: start-jira.sh 
2. Open Jira in your browser.
3. Follow the instructions on the screen to complete the setup.

Post-upgrade landing page

After the successful upgrade, you should see the post-upgrade landing page. It provides information about the new version.

1. Need to know: The list of new features that might affect your work as an admin.
2. User apps: The status of your apps after the upgrade.
3. Application links: The status of your application links.
4. Release notes: The link to the release notes where you can see more detailed information about the version you've upgraded to.

Step 2. Copy upgraded Jira as a template

Copy the new installation directory with all the modifications to another location. So, you’ll have a template that you'll later copy to other nodes.

Step 3: Upgrade apps

Now, it's time to work with third-party apps in Jira. If you've decided to disable the apps or if you’ve successfully upgraded the apps in the status Compatible once both are updated in your test environment, you can do this in production. 

1. Go to Administration > Manage apps.
2. Select Manage apps.
3. Upgrade the apps to supported versions.
4. Once the apps are upgraded, enable them. 

For more information about statuses and apps, see Preparing Jira for the 9.4 upgrade.

If you have removed all apps, now you can install the compatible versions of the apps.

Step 4 (Optional) Updating Jira Service Management

Your Jira instance has been upgraded. If you're using Jira Service Management, you can update it directly in Jira, without downloading a separate installer:

1. Go to Administration > Applications.
2. In Versions and licenses, upgrade Jira Service Management. The app will be automatically updated to a compatible version.

Step 5: Rebuild index

Since the old Jira index is incompatible, reindex Jira to rebuild it. Reindexing might take some time, depending on how many issues and apps you have.

1. Go to Administration > System.
2. In the left panel, select Indexing.
3. In the Options, select Full re-index.
4. Select the Re-index button.

 Learn more details about the index startup procedure in Jira 9.4

Step 6: Re-enable automatic reindex

If you disabled the automatic reindex earlier, you can re-enable it now.

To do this, in the file <jirahome>/jira-config.properties, remove the added property upgrade.reindex.allowed=false.

Upgrading remaining nodes

You should have the ready Jira template and upgraded apps and index data in the shared directory. Now, copy the template to other nodes and start them one by one.

1. Copy the template installation directory to the new node.
2. If the path to the local home directory is different on this node, update it in the setenv.bat or setenv.sh file.
3. Start Jira on this node.
4. Repeat these steps on the next node.

To check if the upgraded nodes are joining the cluster:

1. Go to Administration > System.
2. In the left-side panel, select Clustering.