Migrating Bitbucket Server to another server
This page describes how to move your Bitbucket Server 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 Server data.
- Move the Bitbucket Server installation to the new location, and update the value of the
BITBUCKET_HOMEenvironment variable. - Update the Bitbucket Server bitbucket.properties file. This will be necessary if you were unable to use the Migration Wizard in Step 2.
See also the Bitbucket Server upgrade guide. You can upgrade Bitbucket Server either before or after you migrate Bitbucket Server. This page does not describe any aspect of the upgrade procedure.
On this page:
1. Prepare for the migration
In preparation for migrating Bitbucket Server 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 Server.
- Check for any known migration issues in the Bitbucket Server Knowledge Base.
- Alert users to the forthcoming Bitbucket Server service outage.
- Ensure that users will not be able to update existing Bitbucket Server data during the migration. You can do this by temporarily changing the access permissions for Bitbucket Server.
- Make sure you have created a user in Bitbucket Server (not in your external user directory) that has System Administrator global permissions so as to avoid being locked out of Bitbucket Server in case the new server does not have access to your external user directory.
2. Move the Bitbucket Server data to a different machine
This section gives a brief overview of how to move the Bitbucket Server 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 Server data is moved when you move the Bitbucket Server installation.
The Bitbucket Server data includes the data directories (including the Git repositories), log files, installed plugins, temporary files and caches.
You can move the Bitbucket Server 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 Server 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 Server, use the Bitbucket Server 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 Server (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 Server to a different machine
This section describes moving the Bitbucket Server installation to a different machine.
- Stop Bitbucket Server. 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. The home directory location is defined:
- on Windows, by the
BITBUCKET_HOMEenvironment variable, or by theBITBUCKET_HOMEline of<Bitbucket Server installation directory>/bin/set-bitbucket-home.bat on Linux and Mac, by the
BITBUCKET_HOMEline of<Bitbucket Server installation directory>/bin/set-bitbucket-home.sh.
- on Windows, by the
Copy the archive of the Bitbucket home directory to the new machine and unzip it to its new location there.
For production environments the Bitbucket Server home directory should be secured against unauthorized access. See Bitbucket home directory.
- When moving the Bitbucket Server 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 Server in the new location by doing one of the following:
- Make an archive of the old Bitbucket Server installation directory and copy it across to the new machine.
- Install the same version of Bitbucket Server from scratch on the new machine.
- Redefine the value for
BITBUCKET_HOME, mentioned in Step 2. above, in the new<Bitbucket Server 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 Server embedded database, or you used the Migration Wizard to move the Bitbucket Server data, you should now be able to start Bitbucket Server 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 Server is working correctly, revert the access permissions for Bitbucket Server to their original values.
- If you moved the Bitbucket Server 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 Server 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 Server configuration
If you moved the Bitbucket Server 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 Server 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 Server is working correctly, revert the access permissions for Bitbucket Server to their original values.