Migrating Bitbucket Data Center to another server
This page describes how to move your Bitbucket Data Center installation from one physical machine to a different machine. For most scenarios, the overall procedure involves the following 4 steps, although your situation may not require all of these:
- Prepare for the migration.
- Move the Bitbucket Data Center data.
- Move the Bitbucket Data Center installation to the new location, and update the value of the
BITBUCKET_HOMEenvironment variable. - Update the
bitbucket.propertiesfile. This will be necessary if you were unable to use the Migration Wizard in Step 2.
See also the upgrade guide. You can upgrade either before or after you migrate. This page does not describe any aspect of the upgrade procedure.
On this page:
1. Prepare for the migration
In preparation for migrating Bitbucket Data Center to another server, check that you have done the following:
- Confirm that the operating system, database, other applicable platforms and hardware on the new machine will comply with the requirements for Bitbucket Data Center.
- Check for any known migration issues in the Knowledge Base.
- Alert users to the forthcoming Bitbucket Data Center service outage.
- Ensure that users will not be able to update existing Bitbucket Data Center data during the migration. You can do this by temporarily changing the access permissions for Bitbucket Data Center.
- Make sure you have created a user in Bitbucket Data Center (not in your external user directory) that has System Administrator global permissions so as to avoid being locked out of Bitbucket Data Center in case the new server does not have access to your external user directory.
2. Move the Bitbucket Data Center data to a different machine
This section gives a brief overview of how to move the Bitbucket Data Center data to a different machine. You do not need to do anything in this section if you will continue to use the embedded database. The Bitbucket Data Center data is moved when you move the Bitbucket Data Center installation.
The data includes the data directories (including the Git repositories), log files, installed plugins, temporary files and caches.
You can move the data:
- from the embedded database to a supported external DBMS.
- to another instance of the same DBMS.
- from one DBMS to another supported DBMS (for example, from MySQL to PostgreSQL).
You can also move the actual DBMS. Atlassian recommends that for large installations, Bitbucket Data Center and the DBMS run on separate machines.
There are 2 steps:
- Create and configure the DBMS in the new location. Please refer to Connect Bitbucket to an external database, and the relevant child page, for more information.
- Either:
- If the new location is currently visible to Bitbucket Data Center, use the Bitbucket Database Migration Wizard. Please refer to Connect Bitbucket to an external database, and the relevant child page, for more information.
- If the new location is not currently visible to Bitbucket Data Center (perhaps because you are moving to a new hosting provider), you need to perform a database export and then import the backup to the new DBMS. Please refer to the vendor documentation for your DBMS for detailed information.
You will also need to update the bitbucket.properties file in the<Bitbucket home directory>as described below.
3. Move Bitbucket Data Center to a different machine
This section describes moving the Bitbucket Data Center installation to a different machine.
- Stop Bitbucket Data Center. See Start and stop Bitbucket.
- Make an archive (such as a zip file) of the Bitbucket home directory. The home directory contains data directories (including the Git repositories), log files, installed plugins, SSH fingerprints, temporary files and caches.
Copy the archive of the Bitbucket home directory to the new machine and unzip it to its new location there.
For production environments the home directory should be secured against unauthorized access. See Bitbucket home directory.
- When moving the home directory from Windows to Linux or Mac, make sure that the files within
<Bitbucket home directory>/git-hooksand<Bitbucket home directory>/shared/data/repositories/<repoID>/hooksdirectories have the executable file permission set.
- Set up an instance of Bitbucket Data Center in the new location by doing one of the following:
- Make an archive of the old installation directory and copy it across to the new machine.
- Install the same version of Bitbucket Data Center from scratch on the new machine.
- Redefine the value for
BITBUCKET_HOME, mentioned in Step 2. above, in the new<Bitbucket installation directory>, using the new location for your copied home directory. See Set the home directory for more information. - If you are continuing to use the Bitbucket Data Center embedded database, or you used the Migration Wizard to move the data, you should now be able to start Bitbucket Data Center on the new machine and have all your data available. See Start and stop Bitbucket. Once you have confirmed that the new installation of Bitbucket Data Center is working correctly, revert the access permissions for Bitbucket Data Center to their original values.
- If you moved the data by performing a database export and import, carry on to Step 4. below to update the bitbucket.properties file in the
<Bitbucket home directory>.
Using rysnc to move your installation
Another way to move your Bitbucket Data Center installation is to use rsync (learn more at ss64.com). This option may be helpful if you want to avoid the system downtime that using an archive file will require.
If you use rsync, make sure to use the --delete option. Without it, if you run rsync more than once, files removed from the source machine will not be removed from the target. As a result, the two filesystems will not match, and this can lead to problems with your installation.
4. Update the Bitbucket Data Center configuration
If you moved the Bitbucket Data Center data by performing a database export, you must update the bitbucket.properties file within <Bitbucket home directory>/shared with the changed configuration parameters for the database connection.
The configuration parameters are described in Configuration properties.
Once the configuration parameters are updated, you should be able to start Bitbucket Data Center on the new machine and have all your data available. See Start and stop Bitbucket. Once you have confirmed that the new installation of Bitbucket Data Center is working correctly, revert the access permissions for Bitbucket Data Center to their original values.