Jira Software 8.0.x upgrade notes

Jira Software release notes

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

Here are some important notes on upgrading to Jira Software 8.0.

For details on the new features and improvements in this release, see the Jira Software 8.0.x release notes


  Upgrade notes

Here's a summary of changes and important notes from Jira 8.0.

Increase pool-max-size on upgrade

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.

Apache Tomcat 8.5.35

We've upgraded Apache Tomcat to 8.5.35 in Jira 8.0.2.

Changes to indexing

One of the changes coming with Jira 8.0 is the upgrade of the Lucene library, which is responsible for the index in Jira. This change improves indexing (and searching), but it also makes your current index incompatible with the new version. That’s nothing to worry about, as you can rebuild the whole index by ‘reindexing’ Jira - an action you would probably run after a normal upgrade anyway. After reindexing, the index will be compatible with any later version.

New index directory...
New index directory

Your current index will remain in <home-directory>/caches/indexes (feel free to delete it after the upgrade). From now on, the new index will be stored in the following directory:

<home-directory>/caches/indexesV1
How does it affect the upgrade...
How does it affect the upgrade

The new index will trigger an automatic reindex in Jira just after the upgrade (more precisely, when you start Jira). Because of that, there’s a great chance you’ll reindex twice - after starting Jira and after making some changes that require reindexing, for example, upgrading plugins. Reindexing might be really time consuming in large Jira instances, that’s why we’re recommending that you disable the automatic reindex and run it manually later, when you’re ready.

How to disable automatic reindex...
How to disable automatic reindex

We’ve included steps needed to disable the automatic reindex in our upgrade procedures. If you’re looking for a quick answer, though, you’ll need to add the following line to the <home-directory>/jira-config.properties file before you start Jira after the upgrade.

upgrade.reindex.allowed=false
Recommended actions

(tick) Disable automatic reindex to avoid reindexing twice, and run the reindex manually, whenever you’re ready.

(info) If your Jira instance is small and an extra reindex doesn't sound like a problem, you don't need to disable it. Your upgrade won't be affected in any way; it's just for saving you some time.

Disabling incompatible apps (add-ons)

You need to disable apps that are incompatible with Jira 8.0 or upgrade them to compatible versions, if these are available. Incompatible apps might block the upgrade and the Jira startup, because they're using elements that are no longer available or that have changed in the new version, like the Jira index, APIs, or some parts of the UI.

Recommended actions

(tick) Disable all incompatible apps, or upgrade them if they have compatible versions. For more info on what you should do, see Preparing for the upgrade.

(info) We always recommend that you test the upgrade in a test environment. Once you upgrade the test environment to Jira 8.0, you can try enabling the incompatible apps and see how they behave with the new version. If they don't affect your Jira instance in a significant way, you can use them with 8.0 even if they haven't been declared as compatible yet.

Jira might take longer to start after the upgrade

One of the improvements we’re shipping in Jira 8.0 is the addition of new indexes to two of the most heavily used database tables (changeitem, changegroup). Thanks to that, issues will load faster, and so will queries executed against the database to retrieve the data that issues contain.

Adding indexes to these tables can take several minutes, and will take place when you start Jira after the upgrade. Learn more

Zero downtime upgrade for Jira Data Center isn't supported

Because of significant changes we've introduced to the Jira platform in 8.0, we can't support the zero downtime upgrade from Jira Data Center 7.x to 8.0. To upgrade, you'll need to use a regular upgrade method. Zero downtime upgrade will be available again when upgrading within the 8.x line.

Changes to several configuration properties

In Jira 8.0, we’ve changed default values for some of the properties related to indexing, and also made several properties obsolete. 

Obsolete properties:

  • jira.index.commitpolicy
  • jira.index.batch.maxbuffereddocs
  • jira.index.interactive.maxbuffereddocs
  • jira.index.batch.maxmergedocs
  • jira.index.interactive.maxmergedocs
  • jira.index.batch.mergefactor
  • jira.index.interactive.mergefactor

Properties that have new default values:

  • jira.index.issue.threads (20)
  • jira.index.batch.maxrambuffermb (1024)
  • jira.index.interactive.maxrambuffermb (1024)

You can always view the jpm.xml file to see all supported properties, and their current values.

The maxrambuffermb properties define the maximum size of a memory write buffer for Lucene documents queued to be saved into the index files. We’ve increased it to better handle issues with large number of custom fields. Because of this change, we’ve also increased the default maximum heap size (xmx), as described below.

Memory requirements

Because of the increase in maxrambuffermb, we’ve also increased the default maximum heap size (xmx).

PropertyJira 7.xJira 8.0
Xmx7682048

jira.index.batch.maxrambuffermb

1001024

jira.index.interactive.maxrambuffermb

161024

Jira 8.0 should require less memory, however we still need the xmx value to be higher than maxrambuffermb. If you already had xmx set to 2GB, you shouldn’t need to increase this value. 

If you’re running Jira on a 32-bit system, the 2GB heap size will be too high, and you’ll need to decrease it, as described below.

Decreasing heap size for Jira on 32-bit systems

This applies only if you’re installing/upgrading Jira manually by using the archive. Installers will do it for you.

If you’re installing/upgrading Jira on a 32-bit system, you need to decrease the maximum heap size available to Jira. The default for 64-bit systems in Jira 8.0 is 2GB, which is too much for a 32-bit system, and may not fit into the available memory. We’ve created a new setenv32.bat/.sh file that has all the right settings, you just need to put it in the right place.

Tell me how to do this...

Complete these steps after extracting files from the archive, but before starting Jira:

Step 1: Rename the default setenv file.

  1. Go to <Jira-install-directory>/bin, and delete the setenv.bat / .sh file (or change its name).

  2. Rename setenv32.bat / .sh to setenv.bat / .sh. Jira will use this file on startup.

Step 2: Add the properties to the jira-config.properties file.

  1. Go to Jira’s home directory, and edit the jira-config.properties file. If the file isn’t there, you can create it.

  2. Add the following properties: 

    jira.index.batch.maxrambuffermb=256
    jira.index.interactive.maxrambuffermb=256

New configuration for MySQL 5.7

We've added new configuration steps for MySQL 5.7 to let you use 4-byte characters in Jira. Your old configuration will still work, but you won't be able to use 4-byte characters. For more info, see Connecting to MySQL 5.7.

Additionally, we've added and extra column to MySQL tables, which might result in Jira's slower startup just after the upgrade. 

Reduced logging to the catalina.out file

Jira applications used to mirror the application log output (atlassian-jira.log) in the Tomcat log file, catalina.out. Since the catalina.out file couldn’t be rotated by Jira using the Log4j configuration (like it happens with the application log), the file grew significantly and didn’t really contain any unique or useful events from Jira. Jira admins could work around this issue by using log-rotation scripts at the OS level, but that complicated the setup.

To fix this issue, we’ve removed mirroring the log output to catalina.out (process Stdout), leaving only the following basic events that are useful for our Support teams:

log4j.logger.com.atlassian.jira.(upgrade|startup|config.database)

We’ll keep logging all events into the atlassian-jira.log file, like it was before. Also, we’ve increased the number of atlassian-jira.log rotated files from 5 to 10.

Apache Tomcat upgrade

We've upgraded Apache Tomcat to version 8.5.32, which requires that you make changes to the server.xml file. We've made this change in Jira 7.12.2. If you're upgrading from this version or any later, you should've already done these steps.

What's the problem?

The Apache Tomcat server is filtering out requests that contain special characters, making them fail. That's because Tomcat is using a different encoding and URI standard than most browsers (details here). The problem is most visible when searching with JQL as you’d use a number of special characters when doing it (e.g. []<>), but it can also affect other pages in Jira. 

How can I solve this?

To solve the problem, edit the server.xml file, and add properties that make Tomcat accept special characters in the requests.

  1. Go to <Jira-installation-directory>/conf, and edit the server.xml file.
  2. Find all connectors your application is using. Just search for Connector in the file, or look at the example below.
  3. Add relaxedPathChars="[]|" relaxedQueryChars="[]|{}^\`"<>" to the connector properties in server.xml. For example:

    <Connector port="8080" relaxedPathChars="[]|" relaxedQueryChars="[]|{}^&#x5c;&#x60;&quot;&lt;&gt;" maxThreads="150" minSpareThreads="25" connectionTimeout="20000" enableLookups="false" maxHttpHeaderSize="8192" protocol="HTTP/1.1" useBodyEncodingForURI="true" redirectPort="8443" acceptCount="100" disableUploadTimeout="true" bindOnInit="false"/>
  4. Restart Jira.
  5. (Data Center) Repeat these steps on each node.

Upgrade to the DVCS plugin

If your Jira Software Server or Data Center instance is connected to Bitbucket Cloud, it’s through the Jira DVCS connector plugin.

Due to GDPR regulations and the personal data protection they require, we've needed to make some changes to the API's that Bitbucket Cloud has available. These changes happen in two phases. Phase one will be live on Bitbucket Cloud by the 10th of May, 2019, and Phase two will go live on the 1st of September, 2019.

What you need to do as a result is to upgrade your Jira Software instance or upgrade your Jira DVCS connector plugin to the relevant version. For more information, see Jira KB

 End of support announcements

In Jira 8.0, we've ended support for the following platforms:

  • MySQL 5.5
  • PostgreSQL 9.3

For more info, see End of support announcements.

 Known issues

Something to be aware of when upgrading to Jira 8.0.

Jira fails to install as a Windows service

This issue has been fixed in Jira 8.0.1.

Jira fails to install as a Windows service after a regular installation or after an upgrade to Jira 8.0. This problem is caused by an incorrect path to your Java installation. If the path contains spaces (which is often the case), the service installation will fail. You can read more about this issue here.

How can I solve this?

The Jira installer is bundled with Java Runtime Environment (JRE), so the easiest way to fix this issue is to set the JRE_HOME environment variable from within the Jira installation directory. 

  1. Open Windows command prompt as an Administrator.
  2. Navigate to the Jira installation directory.
  3. Set the JRE_HOME environment variable like shown below:

    set JRE_HOME=.\jre
  4. Install the Windows service again by using the following command:

    .\bin\service install Jira

I’m using a different Java distribution…

If you’re not using the bundled JRE, or installed Jira from the ZIP archive, you need to set the JRE_HOME (or JAVA_HOME) environment variable to a path that doesn’t contain any spaces. You can do this by using the short 8.3 form of your regular path, like in the following example:

Regular path
set JRE_HOME=C:\Program Files\Java
Short path
set JRE_HOME=C:\Progra~1\Java

Installation directory for Plugin 1 type apps

Make sure that your P1 apps are installed in <Jira-install-dir>/atlassian-Jira/WEB-INF/lib. If you install these apps along with regular apps from Atlassian Marketplace in <jira-home-dir>/plugins/installed-plugins, they won’t work in Jira 8.0. For more information, see Installing Marketplace apps.

 App developers

See Preparing for Jira 8.0 for any important changes regarding apps.

 Upgrade procedure

See Upgrading Jira applications for complete upgrade procedures, including all available upgrade methods and pre-upgrade steps that are required for Jira 8.0. For a more tailored upgrade, go to  > Applications > Plan your upgrade. We’ll recommend a version to upgrade to, run pre-upgrade checks, and provide you with a custom upgrade guide with step-by-step instructions.

Last modified on May 8, 2020

Was this helpful?

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