Documentation for JIRA 4.4. Documentation for other versions of JIRA is available too.
On this page:
Before You Upgrade
Please note the following points before starting your upgrade:
Tomcat, Apache and mod_proxy setup
Unlike previous versions of JIRA, the new JIRA 4 Dashboard frequently makes HTTP requests to itself. For this reason, the hostname, port and protocol (http/https) must be correct throughout all portions of the request chain. Additionally, if you are using SSL, JIRA's JVM must be able to trust the SSL certificate on a JIRA response. If your setup is not configured correctly, the Dashboard in JIRA will not work. Please read this knowledge base article if you are having problems.
JIRA 4.0 introduces some significant licensing changes. Before you begin the upgrade, please go to my.atlassian.com for your upgraded license. Please note, any existing 3.x license files will not work with 4.0.
JIRA has moved to a user-based licensing model in JIRA 4.0. This means that you will need to calculate the number of users in your JIRA system to determine what license you will need, before you can complete your upgrade. For more information on this, please see the JIRA pricing changes FAQ.
Once you have upgraded your license, please follow the instructions below:
Please ensure that you follow the instructions in the general JIRA upgrade guide (non-version specific), as well as the JIRA 4.0 specific instructions in the sections below. The general upgrade guide contains important tasks that are essential for getting your upgraded JIRA instance to work correctly (e.g. merging jira-application.properties
customisations from the old instance to the upgraded instance).
Please note that upgrading to JIRA 4.0 may take a long time, depending on the size of your instance as well as server and database performance. During the upgrade, several upgrade tasks will need to run to upgrade your data to be ready for JIRA 4.0, such as:
Please schedule sufficient downtime time for the upgrade in your production environment. It is recommended to run an upgrade first in a test environment to see how long the upgrade will take for your data set and hardware configuration.
If you are running JIRA under version 6 (1.6) of the Sun JRE, please ensure that you are running a point release JRE 6 (1.6) Update 10 or higher. The reasons for this are:
JIRA 4.0 introduces a new REST plugin type based on Jersey, which will not work with JRE 6 - JRE 6 Update 3. If you are running JIRA with one of these versions of the JRE you will see the following errors:
java.lang.LinkageError: JAXB 2.0 API is being loaded from the bootstrap classloader, but this RI (from bundle://16.0:3/com/sun/xml/bind/v2/model/impl/ModelBuilder.class) needs 2.1 API. Use the endorsed directory mechanism to place jaxb-api.jar in the bootstrap classloader. (See http://java.sun.com/j2se/1.5.0/docs/guide/standards/)
Note: JRE 5 (1.5) doesn't have this problem since it doesn't bundle JAXB.
JIRA 4.0 has a new directory structure — for details, please see Important Directories and Files.
Please ensure that you set the jira.home
property as described here.
The following browsers are recommended for use with JIRA 4:
Tip: If you are looking for our recommended databases and applications servers, you can find them here:
If any of your users have saved invalid filters, the new 'Advanced Search' screen may appear when they try to display them.
mail.mime.decodeparameters=true
Refer to Setting Properties and Options on Startup for instructions.
JIRA 4.0 introduces a new system field, the Resolution Date. This field provides the date when an issue last entered into a 'Resolved' workflow state. When upgrading to JIRA 4.0, an upgrade task will run, calculating the Resolution Date for every resolved issue in your system. If you have a large number of issues, this may take a long time. The speed at which this upgrade task runs can be improved by ensuring that your database statistics are up to date for your changegroup and changeitem tables (to ensure the database will select the most effective query plan).
For example, on Postgres this can be done by executing the following commands:
jiratest=# ANALYZE changegroup; ANALYZE jiratest=# ANALYZE changeitem; ANALYZE
JIRA's RPC interface now provides two new methods to retrieve an issue's Resolution Date:
The RemoteIssue class was left unchanged, to ensure backwards compatibility of RPC clients.
If you are using an Oracle or MySQL database, please note that two column data types have been changed.
Therefore, the easiest way to upgrade to JIRA 4.0 is to perform an XML backup and restore as described in the Migrating JIRA to Another Server instructions.
If in the past, instead of performing an XML backup and restore, you have been upgrading by "pointing" the new version of JIRA at an old database, this is still possible. However, the procedure is more complicated. You will need to use SQL scripts to perform database schema changes.
For details (and the scripts), please see JIRA 4.0 Database Schema Changes for MySQL and Oracle .
JIRA 4.0 now bundles most of the charts previously provided by the JIRA charting plugin. If you currently have the JIRA charting plugin installed (v1.4.1 or previous) in WEB-INF/lib
, please remove it as otherwise JIRA will fail to start.
The following charts have not been bundled with JIRA 4.0. If you are using any of the following charts, you will need to upgrade to version 1.5 of the JIRA charting plugin:
If you are using the JIRA Toolkit, you will need to upgrade it to the latest version.
You will also need to install it in your JIRA home directory, rather than your atlassian-jira/WEB-INF/lib/
directory as it now runs in an OSGi container. Read Managing JIRA's Plugins for more information.
GreenHopper for JIRA 4.0 is now available for use with JIRA 4.0. You can download it on the GreenHopper Plugin for JIRA Downloads page. Please follow the GreenHopper Installation and Upgrade Guide for instructions on how to upgrade GreenHopper.
Please note, you need to upgrade your GreenHopper license before you can use GreenHopper with JIRA 4.0. Any existing GreenHopper license files will not work with JIRA 4.0. You can obtain a license from http://my.atlassian.com.
Prior to JIRA 4.0, it was possible to create two statuses whose names differed only in case (e.g. 'Resolved' and 'RESOLVED'). If you upgrade to JIRA 4.0, this will lead to ambiguities. Consider this scenario:
Additionally, you will receive ambiguous results if you attempt to perform a search by name on the status in the Advanced Search (e.g. "Status = In Progress (Services)").
To resolve this issue, we recommend that you ensure that each issue status is distinct by renaming the duplicate statuses appropriately. You may also need to update any issue filters that you have set up.
JIRA 4.0 introduces several changes that may break existing plugins.
There are now two different types of plugins. Each type of plugin needs to be installed into a different directory to work. Read Managing JIRA's Plugins for more information.
If you are using a plugin that is not shipped with JIRA, the plugin may need to be updated to work with JIRA 4.0. If the plugin was written by you, please read through Updating JIRA Plugins for JIRA 4.0 and see if any of it is relevant to your plugin. If you are using a plugin written by a third party, please check with the plugin's author to see if the plugin has been tested with JIRA 4.0.
Running JIRA v4.0 may require more RAM than running v3.x.
The default settings (suitable for small to medium usage) for standalone allocates a total of 512MB memory to the JIRA application.
Please ensure your server has enough available RAM to cover this.
If you are installing JIRA as a WAR/EAR, then you may need to increase the amount of "PermGen" memory allocated to JIRA. 256MB PermGen is recommended.
In addition to the points listed above, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.
Please also note the following: