Migrate from InCloud to Standalone

This page provides instructions for migrating from a YouTrack InCloud instance that is hosted by JetBrains to a self-hosted YouTrack Standalone server. When you perform this type of migration, we assume that:

Your YouTrack Standalone installation is either empty or can be overwritten.
You plan to retire your InCloud instance and work exclusively with the Standalone server or use the InCloud instance for another purpose.

You have already purchased a licence for YouTrack Standalone that meets or exceeds the number of active users in your hosted instance. You need to enter the License User Name and License Key during the migration, so keep these values handy.

If you currently use the free plan and are not migrating to a commercial Standalone license, you can use the value for the free version of YouTrack Standalone as shown here:

Field	Value
License User Name	YouTrack Default
License Key	`42bd2ce4dbaf8554bf082946a1c039d4384e81a99ed53fb75215c1b6ace8d34cf66889fdeee418cbe93d54f38f6e94a8a05a0108234b1955582d566283e3d084b23a0b8b52b016b0e610abcbbe7573fa3ff8fb3cdc9346dc94ef5f596f5b12719abcb02e6fae23d98f53f22a01788066aac7298b7fe79cc3dcd6f8df2fb41ab4`

If you simply want to import issues from a YouTrack InCloud instance to an existing YouTrack Standalone server, see Import from YouTrack.

Many administrators install and test YouTrack Standalone before they migrate data from an InCloud instance and make it available to other users. In this case, the standalone installation only contains test data that can be deleted. If you set up a YouTrack Standalone installation for testing purposes, we recommend that you uninstall the test installation and migrate the data from your YouTrack InCloud instance to a clean installation of YouTrack Standalone.

Export Your YouTrack InCloud Database

The first step is to export a backup copy of your YouTrack InCloud database.

To export your YouTrack InCloud database:

In YouTrack InCloud, open the Administration > Server Settings > Database Export page.
Click the Update export file button.
When the export file has finished updating, click the Download link.
- The backup file is saved to your local directory.

Install YouTrack Standalone

The next step is to install YouTrack Standalone with the data from your YouTrack InCloud instance.

For MSI and ZIP distributions, you can automatically import your data during installation.
For the JAR distribution, you need to install YouTrack first, then extract the data from your database backup file.

Note that the backup of your YouTrack InCloud database contains the base URL and license for your InCloud instance. Follow the instructions in this guide to update these properties and properly configure your YouTrack Standalone server.

To migrate to YouTrack Standalone with an MSI or ZIP distribution:

Download and install the MSI or ZIP distribution. Follow the standard installation guide up to the step where the web-based Configuration Wizard opens in your default browser.
- For the MSI installation guide, see MSI Installation.
- For the ZIP installation guide, see ZIP Installation.
In the Configuration Wizard, click Upgrade.
On the Select Upgrade Source page, select the database backup that you exported from your YouTrack InCloud instance in the previous procedure.
Click the Next button.
- The Confirm Settings page opens.
- The Base URL displays the URL of your YouTrack InCloud instance.
Change the Base URL setting to the URL of your YouTrack Standalone server.
Click the Upgrade button.
- The configuration is applied to your YouTrack Standalone server.
- The YouTrack service starts using the license that is associated with your YouTrack InCloud instance. You are notified that the license can only be used for YouTrack InCloud.
Click the link to access the Global Settings page.
Enter the License User Name and License Key for YouTrack Standalone.
Click the Save button.
- Your YouTrack server runs using the updated license.
- The data from your YouTrack InCloud instance is available for use on your YouTrack Standalone server.

To migrate to YouTrack Standalone with a JAR distribution:

Download the JAR distribution and upload it to your server.
Before you run the YouTrack service, extract the data from your YouTrack InCloud instance to the data directory of your standalone installation.
- Check the data directory of your standalone installation and verify that it is empty. The default location of the database is in the teamsysdata folder in the home directory of the user account that runs YouTrack. If there are any files or folders in this directory, delete them.
- Extract the contents of the database backup file to your data directory. After extraction, the data directory contains two folders: hub and youtrack.

Run YouTrack Standalone from the command line. Use the following Java start parameters to configure the server:

Parameter	Description
jetbrains.youtrack.baseUrl	Set the Base URL property to the base URL of your YouTrack Standalone server.
jetbrains.youtrack.licenseName	Set the name of your YouTrack license to the name of your YouTrack Standalone license.
jetbrains.youtrack.licenseKey	Set the license key of the YouTrack license to your license key for YouTrack Standalone.

For example:

java -Xmx1g -XX:MaxMetaspaceSize=250m -Djava.awt.headless=true
-Djetbrains.youtrack.baseUrl="http://www.mystandaloneserver.com:[port]
-Djetbrains.youtrack.licenseName="YouTrack Free Pack User"
-Djetbrains.youtrack.licenseKey="fa210d1d87408e18c6cfb9e09991aa5f9781410fcf660e47a366fcf83d5d25085e4b41e7ffd54256424e32a3aac1d5ec7464d98421b1a3068c8642279d0e0d85cb2e569b0f20fc5174331e40fe2e09f4291d14d8058015a71ef2ab64c2847fc82f71e0038b4ebd53b7e0e4d6ec7348fe0a0598d8b78f253914aa4959a59eb997"
-jar youtrack-<version>.jar [host:]<port>[/contextPath] [config file path]

Your YouTrack server runs using the updated base URL and license.
The data from your YouTrack InCloud instance is available for use on your YouTrack Standalone server.

Once you have verified that everything works as expected, remove the custom start parameters from the command that you use to start the server.

Migrate Notification Services

By default, YouTrack InCloud instances use email and Jabber services that are hosted by JetBrains to deliver notifications. After you migrate to a YouTrack Standalone installation, these services are no longer available. If you're not already using your own notification services, you need to set them up and connect them to your YouTrack Standalone installation.

For notifications over email, set up your own SMTP server, then follow the instructions to enable email notifications.
For notifications over Jabber, set up your own Jabber service, then follow the instructions to enable notifications over Jabber.

Migrate Mailbox Integration

If you used mailbox integration with a default mailbox configuration in your YouTrack InCloud instance, it would stop functioning after the migration. The default mailbox configuration is only available for the cloud YouTrack instances.

To migrate the mailbox integration from InCloud to Standalone, choose one of the two options:

Option	Result
Delete the mailbox configuration	The default mailbox configuration migrated from the YouTrack InCloud is removed along with the mailbox rules. The issues, comments, attachments, and users created from emails remain in YouTrack. However, the references to the original emails are lost. This means that if you add a new mailbox integration, connect it to the same mailbox and try to process the same emails again, it will create duplicate entities in YouTrack.
Reconfigure the mailbox connection settings to match the new environment	The mailbox rules do not require any updates, so you can simply use the same rules with the new mailbox. Even though the default cloud mailbox is no longer accessible, you can use the same setup with a changed support email. In this case, the threads in the mailbox and in comments will not be interrupted and just continue with the new support address.

Option

Result

Delete the mailbox configuration

The default mailbox configuration migrated from the YouTrack InCloud is removed along with the mailbox rules.

The issues, comments, attachments, and users created from emails remain in YouTrack. However, the references to the original emails are lost. This means that if you add a new mailbox integration, connect it to the same mailbox and try to process the same emails again, it will create duplicate entities in YouTrack.

Reconfigure the mailbox connection settings to match the new environment

The mailbox rules do not require any updates, so you can simply use the same rules with the new mailbox.

Even though the default cloud mailbox is no longer accessible, you can use the same setup with a changed support email. In this case, the threads in the mailbox and in comments will not be interrupted and just continue with the new support address.

Last modified: 29 September 2021