Best practices for migrating Jira from one Data center to another

Owned by Vijaya Durga Vempa
Last updated: Mar 08, 2024
4 min read

Overview

This article explains the best practices for migrating jira from one data center to another using the Configuration Manager for Jira (CMJ) app.

Best Practices

Versions and Compatibility

  1. It is recommended to have the latest version of the Configuration Manager for Jira app installed on both the instances, the source, and the target so that it has the latest features and bug fixes. You can check the latest compatible versions from the following link:https://marketplace.atlassian.com/apps/1211611/configuration-manager-for-jira-cmj/version-history

  2. Snapshots are forward compatible, meaning that snapshots created using older versions of CMJ can be used on the newer version in target but not vice versa. Ensure that the snapshot is created using a CMJ version equal (or lower) than the CMJ version on the target Jira instance.

  3. The CMJ app now permits a discrepancy in Jira versions between the source and the target instances as long as both instances utilize the same app version. This deviation from the previous recommendation of uniform Jira versions across instances offers greater flexibility in Jira deployments. It is always suggested to check the compatibility matrix to ensure the versions of the CMJ are the same between the target Jira and the source Jira instances. For more information, refer to this link: Compatibility Matrix.

  4. Snapshot compatibility between Jira versions - specific cases

    1. Snapshots created on versions of Jira before Jira 6.3 will remove all members of the "Transition Issue" permission in permission schemes when deployed on Jira 6.3 and above.

    2. Some Jira versions introduce new configuration objects and remove others, so a snapshot taken on one version might not always work on another.

Attachments

  1. Including the attachment files can make the snapshot grow very large. So, CMJ allows two ways of handling attachments. The attachment metadata (filename, creator, create date, etc.) is generally small and is always included in the snapshot.

    1. Include attachment files in the snapshot. This is the preferred option for moving projects with fewer attachments (roughly less than 100 MB).

    2. Do not include attachment files in the snapshot. If the total attachment size is large, copy the attachments for the exported projects and move them to the target system. During the snapshot deployment, Configuration Manager will present you with an option to provide the path where the files reside on the target system. The snapshot will remain small, and the deployment will speed up. Here is the documentation link for more info: Move Attachments

Users and Groups

  1. We recommend you ensure that the users and the groups are set in advance in the target before migrating to another instance.

  2. It is suggested to go through a phase of ‘user normalization’ before deploying the changes so all users are available on the target in advance. You can read more about this here -   Move Projects (with Issue Data) | User Management Normalization.

  3. Note that CMJ does not support user migration. This is something that our customers need to take care of.

Third-Party Apps Support:

  1. In case you have any third-party apps running in the source instance, before migrating, check if your apps are already present in the list of integrated apps(supported apps) by CMJ from this link:List of all integrated apps. If not, follow the instructions in the link.

  2. Ensure the above apps in your source are installed in the target instance to overcome any app-related data issues.

Pre-migration checks

  1. It is strongly recommended to run the CMJ's Integrity Check for Jira before migrating in the source and the target instances. Fix the issues if any are identified. Here is the relevant link Integrity Check | Run Integrity Check. Another option here is to run the Quick Fix, which allows you to fix the most common problems in the system automatically. The documentation link is Quick Fix

  2. It is also recommended to run Jira's built-in system Integrity Checker and fix the issues related to missing references before migration on both source and target instances. please refer to the document for more info: https://confluence.atlassian.com/adminjiraserver/using-the-database-integrity-checker-938847667.html

  3. It is recommended to perform a test migration before the production migration to capture likely issues in your instance. Before doing so, capture the debug logs explained in the next section.

Debug Logs:

  1. Enable the debug log profile, as shown in the screenshot below, in both the source and the target instances before migration so that you can share the support zip file with us if you face any issues during the migration.

  1. It is recommended to check the release notes, which have the latest release versions, highlights, updates, and resolved Issues that were encountered by the previous versions) Release Notes

More information

Refer to the following document for more information on the CMJ(Configuration Manager for jira) app Concept. The instructions in this article also apply to server-to-DC migration.

Refer to the following document for CMJ operations on data center cluster performance and how to deal with big snapshot deployments to optimize performance Data Center

Related articles:

https://appfire.atlassian.net/wiki/spaces/SUPPORT/pages/114655448

Unknown Compatibility for Configuration Manager Bundle

Parameters and Limitations of CMJ public REST API

Best Practices : Migrating Jira projects from one Jira data center to another data center by following Configuration Manager for Jira(CMJ) Compatibility Matrix

How many licenses do I need?

Â