Servers don’t live forever — and even if they did, changing business or technical requirements would still render them obsolete eventually. Sooner or later, you’ll have to replace or upgrade your server, along with everything running on it.
If that includes Jira, you’ll have to formulate a plan for migrating your Jira instance to a new host server. If you plan correctly, you’ll be able to complete the migration quickly and without missing any data, enabling you to get your instance up and running on the new server smoothly. But if you don’t prepare for the migration properly, you risk data loss, unforeseen delays, and other issues.
This article offers step-by-step instructions on migrating Jira to a new server and on how to merge Jira instances — a way to move Jira projects to another existing Jira deployment. With the help of the guidance below, your Jira migration process will be as smooth and error-free as possible.
Use the menu below for easy navigation:
- Pre-Migration Considerations
- How to Perform a Jira Migration to Another Server Step by Step
- Merging Jira Instances
Pre-Migration Considerations
You might need to migrate your Jira instance to a new server for several reasons. If you are self-hosting Jira on your own server, it may simply have reached its end of life and need to be replaced. Or your company may undergo an internal reorganization that transfers some IT assets to a different department and, by extension, different servers. Your company might also introduce IT policy changes that require you to move to a new hosting provider because of security concerns or the implementation of a new operating system.
Before starting your Jira migration, it’s critical to assess the attendant risks. Chief among them is data loss, which could occur if you fail to back up data before the migration and don’t transfer all data successfully to the new server. Other risks include significant delays in the migration process due to unexpected obstacles, such as software compatibility issues on the new server.
You might also encounter configuration problems that lead to inconsistent behavior between Jira instances on the old server and the new server. These configuration problems can be caused by differences in Jira versions on the two servers, or by changes in the broader software environment. If you move Jira from an on-premises server to a cloud-based environment, for example, differences in the way networking, access control, and other functions are configured in the two environments could lead to undesirable behavior if the issues are not addressed during the migration.
These challenges can disrupt your normal business operations for a prolonged period and have a significant impact on your bottom line. Avoiding them starts with identifying the issues that might impact your Jira migration plans, then taking steps to address them. This guide is a great start, but it can still be difficult to diagnose all of your unique risks ahead of time. Consider working with an Atlassian Solution Partner that has the Jira expertise necessary to ensure you’re doing everything possible to minimize your risk.
How to Perform a Jira Migration to Another Server Step by Step
Below are general instructions to migrating your Jira instance to a new server. Keep in mind that each migration is different, and it pays to consult with the experts before pressing ahead.
Back Up Data
The first step is backing up the data in your existing Jira instance. In order to avoid data corruption, you should disable access to your Jira instance before performing the backup. You can then create an XML backup of your Jira data. Data in XML format can be easily used to repopulate the Jira database on the new server, even if it is a different type of database than on the original server.
Because the XML backup does not include the Jira attachments directory, home directory, or applications directory, you’ll also need to back these up separately. On most Windows systems, these directories are located under C:\Program Files\Atlassian\. On Linux, they are usually located at /var/atlassian. You can do so by copying the directories to a separate disk drive, or by exporting them into a Zip file or similar archive. You can then move the relevant directories to the new server before importing the rest of your Jira data.
Download the New Jira Instance
Once you’ve backed up your data, you’re ready to install Jira on the new server. Do this by downloading the version of Jira you want to install — Jira Core or Jira Software and going through the standard installation based on your operating system.
You may need to download a JDBC driver. Drivers for Microsoft SQL and PostgreSQL are automatically provided by the installation media. You can find one for MySQL here, and one for Oracle databases here. Alternatively, you can copy the driver from your old server to your new one, if it is already up to date.
Migrate Configurations and Modifications
If you have changed any Jira settings from the defaults, you will need to modify the appropriate configuration files on the new server with the customized settings for your environment. The most common customizations include SSL and Java memory adjustments that are modified via the server.xml, Jira-config.properties, and setenv.sh (on Linux) or sevenv.bat (on Windows) files.
You will also need to update dbconfig.xml to point the new server to your database. If your database has not changed, you can use the same dbconfig.xml as you did on the original server. If you've migrated to a new type of database or moved the database to a different server, you'll need to adjust the settings in this file accordingly.
In addition, if your Jira instance depends on integrations with external services hosted on the local server, you'll need to make sure those services are installed and configured to work with your new Jira instance.
You should take into consideration potential licensing issues as well. In most cases, you can simply reuse your same license key for the new server. If you do encounter any license-related issues, contact Atlassian for assistance.
You may need to adjust DNS settings if your Jira instance on the original server depended on a DNS service that could resolve internal hostnames that are not resolvable on the new server. One solution in this situation is to point the new server to the old server's DNS service, if possible. Otherwise, you can change URLs within the Jira database so that they can be handled properly on the new server.
Import Your Data
Finally, you are ready to start Jira and start importing your data. Go to your operating systems service manager and start the application service. Then open Jira in a browser and follow the on-screen instructions. Select I'll set it up myself and choose to setup the connection to the new database. Then, when prompted, choose the option to Import your data and select the XML backup file that you created initially to import your data into the new Jira instance.
After you go through the rest of the installation process, your new Jira server will be ready to use.
Merging Jira Instances
You can also transfer data from your Jira instance to an instance on another server. There are two ways to do so. The simplest method is to migrate individual projects. The Atlassian Marketplace has a selection of third party tools to help with migrating individual projects. Atlassian Solution Partners can assist with deploying, configuring, and leveraging these tools.
The second method involves merging all the projects and associated data from the two instances. This is the best approach if you have a complex Jira installation on one server and want to integrate those resources into a Jira instance that is already set up on a different server.
To do so, first ensure that both Jira instances have been updated to the same version. They may also have to be identical in other aspects that are relevant to the data you are merging. These potentially include plugins, issue types, and workflows in use. After configuring the instances appropriately, back up your data for the instance you plan to transfer data from. Finally, import the data into your second instance as described in Atlassian’s instructions for restoring a project for backup.
If problems arise, or if you are unsure as to how to configure your instances before merging them, seek help from an experienced partner who can guide you through the process.
Ensure Your Migration Proceeds Smoothly
A poorly planned or executed Jira migration process can leave you with a broken Jira deployment or lost data, leading to serious business disruptions. Complications can arise even if you are migrating between two similar servers, and the process can quickly become more difficult if you need to migrate from a Windows server to a Linux server or update your database as part of the migration process.
That's why investing in outside help from the team of Jira experts at Contegix can help ensure that your migration proceeds as smoothly as possible. The Contegix team will assist you in getting your projects and data to your new server quickly and without error.
Contact Contegix to learn more about how we can help with your Jira migration needs.