Upgrading JIRA safely

The recommended upgrade method is essentially:

• create an XML backup of your JIRA data
• install a new instance of JIRA
• create a new database (if you are not using the embedded database)
• ensure the new JIRA is using the new database
• restore the XML backup into the new JIRA

The recommended preliminary testing, and the upgrade process itself, are described in the three steps below (see 'Recommended method').

Alternative method

If you are currently running JIRA 3.7 or later, you could simply connect your new JIRA to your old database (see Connecting JIRA to a database), and let JIRA attempt to updatee the database schema. This can be useful for extremely large installations, where the recommended method of XML backup/restore might take too long. Before you begin, please be sure to backup your data using your normal database backup procedures.

The alternative method will not work if you are upgrading from 3.6.5 (or earlier), as JIRA 3.7+ cannot automatically update older schemas. If you are running JIRA 3.6.5 (or earlier), and cannot use the recommended method of XML backup/restore, you will need to update the pre-3.7 database schema by hand before proceeding with the alternative method.

Step 1. Back up, install JIRA Standalone and test

The first step is to test the new JIRA version, running with your data, before deploying it in production. This allows you to check for problems, and ensures you have a working backup if something goes wrong later.

1. Ensure that users cannot update JIRA while you perform the XML backup (so that your backup will not contain inconsistent data). There are two ways to do this:

   • Make JIRA inaccessible: Shut down JIRA, start it on a private port and do the backup there. If you do this, no-one will be able to access JIRA at all during the backup, even to read issues; or:
   • Make JIRA read-only: In your database, remove write permissions from the database user that JIRA uses. If you do this, people will be able to read issues but not update them. For details please see Making databases read-only for upgrade backups.

   You may want to first set a banner to warn users that JIRA will be inaccessible (or read-only) while an upgrade is performed.

2. Generate an XML backup (Admin -> Import & Export -> Backup) of your data from your existing JIRA.

3. Download and install the Standalone distribution of JIRA into a new directory (do not overwrite your old JIRA instance).

   • Use the recommended tool to unzip the downloaded file.

4. Copy the values of any modified properties from the old WEB-INF/classes/jira-application.properties file to the new one. Do not just copy the file across, as the new version of JIRA could have new properties that are missing in the old file.

5. For any plugins that you had installed in your old JIRA:

   • Download the latest version from the JIRA Extensions site
   • Install the JAR file(s) in your new JIRA
   • If a properties file exists, copy the values from your old properties file and update the new one.
6. If you had made any customisations (code or template), copy them to the new JIRA and test them.
7. If your new instance of JIRA is installed on the same machine as your old JIRA, make sure it is running on a different port (see Changing JIRA Standalone's Port).

8. If necessary, disable email access in your new JIRA instance, to prevent inadvertent SMTP/POP/IMAP access while testing (see the Restore a backup page for details of how to do this).

9. Start up your new instance of JIRA. When you see the Setup Wizard, click the 'Import Existing Data' link. When prompted for the import file, specify the XML backup you created previously. When prompted for an Index Directory, specify a different directory from your old JIRA.

10. Test the standalone JIRA installation, checking that there are no errors in the log file.

Step 2. Upgrade JIRA

Having deployed your data in a new instance of JIRA Standalone, you now have a known-working backup, and can proceed to upgrade your production instance of JIRA. Choose the section below which applies to you, depending on whether you are running:

• JIRA Standalone with the built-in HSQL database
• JIRA Standalone with an external database
• JIRA EAR-WAR

JIRA Standalone (with the built-in HSQL database)

If you are happy running JIRA Standalone with the embedded HSQL database (please note that this database is not recommended for production use), you have almost finished. Proceed to Step 3.

JIRA Standalone with an external database

If you are currently running your old JIRA Standalone with an external database, follow these steps to connect your new JIRA Standalone to the external database:

1. (In JIRA) Create an XML backup (or use the one from the previous section).
2. (In your external database) Create a new database. For instance, if you previously used database jiradb, create database jiradb_36 (for JIRA 3.6) with identical access permissions.
3. Reapply the modifications you made to the conf/server.xml file in your old JIRA Standalone to get your new JIRA Standalone to use your database, but substituting the new database name (jiradb_36 in the above example) in the JDBC URL.
4. Read the latest instructions for your particular database and perform any necessary steps (e.g. changes to the entityengine.xml file). This will include copying the JDBC driver jar file from the common/lib directory of your old JIRA Standalone to your new JIRA Standalone.
5. Start up your new instance of JIRA Standalone. When you see the Setup Wizard, click the 'Import Existing Data' link. When prompted for the import file, specify the XML backup you created previously. When prompted for an Index Directory, specify a different directory from your old JIRA.
6. Proceed to Step 3.

JIRA EAR-WAR

If you have JIRA deployed as a webapp in your own application server, the upgrade process is similar to the initial installation procedure:

1. Download and unpackage the JIRA EAR-WAR distribution into a new directory (do not overwrite your existing JIRA).

   • Use the recommended tool to unzip the downloaded file.

2. Customise edit-webapp/WEB-INF/classes/entityengine.xml (see the configuration overview), referring to the modified entityengine.xml file from your previous JIRA webapp. The entityengine.xml format could have changed, so hand-edit all the relevant lines in the new file (do not just copy the entire old file).

3. Similarly to entityengine.xml, check other files you have customised in edit-webapp/ of your old JIRA. For instance, the osuser.xml file (if you use it) needs porting (it changed formats between 2.5.3 and 2.6, so again a hand-comparison is recommended).

4. Run build.bat or build.sh to build the new webapp.

5. Read the latest instructions for your particular application server and perform any necessary steps. E.g. if your application server needs extra libraries to run JIRA, the extra libraries currently in your application server may be outdated. Download the extra jars package from the relevant application server configuration guide and check.

6. Create a new database (eg. jira_323) with same access permissions as the old one, and edit the JDBC URL in your application server to use the new database. See your application server configuration guide for details.

7. Read the latest instructions for your particular database and perform any necessary steps.

8. Copy the values of the modified properties from the old WEB-INF/classes/jira-application.properties file to the new one. Do not just copy the file across, as the new version of JIRA could have new properties that are missing in the old file.

9. For any plugins that you had installed previously:

   • Download the latest version from the JIRA Extensions site
   • Install the JAR file(s)
   • If a properties file exists, copy the values from your old properties file and update the new one.
10. If you had made any customisations (code or template), copy them to the new JIRA and test them.

11. Now stop the application server, remove the old JIRA webapp from your application server, and copy in the new one.

    Note

    If using Tomcat, delete the Tomcat work directory before restarting to avoid odd JSP problems.
12. Start up your new instance of JIRA. When you see the Setup Wizard, click the 'Import Existing Data' link. When prompted for the import file, specify the XML backup you created previously. When prompted for an Index Directory, specify a different directory from your old JIRA.

Step 3. After the upgrade

1. Immediately after an upgrade, it is recommended that you check your server logs for error messages, even if JIRA appears to be working correctly.
2. If you were running JIRA Standalone as a Windows service before the upgrade, uninstall the service (to ensure that the old JIRA cannot start automatically when the server restarts) and install a new service. For details please see Running JIRA as a Service.
3. If you changed machines when upgrading, you need to change the path to the indexes, attachments and backup directories. This is done once JIRA is running, in the Administration section.
4. Enable email (if you disabled it during testing).
5. If you were previously using External User Management,
   • Copy any customisations in the old WEB-INF/classes/osuser.xml file to the WEB-INF/classes/osuser.xml in your new JIRA instance. (Note: Do not just copy the file across, as the new version of JIRA could have new properties that are missing in the old file.)
   • Enable External User Management in your new JIRA.
6. If you are using LDAP with JIRA, copy your modified values from the old WEB-INF/classes/osuser.xml file to the new one. For details please see Integrating JIRA with LDAP.
7. If you are using Crowd with JIRA, configure your new JIRA to talk to Crowd as described in Integrating Crowd with JIRA.
8. If you had previously allocated additional memory to JIRA, do the same for your new JIRA instance. For more information see Increasing JIRA memory.

• If the upgrade fails for some reason, do not just revert to the old JIRA version — make sure you revert the data too, by importing the pre-import backup that you made in Step 1. The database format will have changed during the upgrade, and is not backwards-compatible.
• The XML cleaner utility is useful if you have XML-related problems.
• If you need help, please raise a support request.