How to Migrate Bitbucket Mirror/Mirror Farm from one server to another server

Still need help?

The Atlassian Community is here for you.

Ask the community


Platform Notice: Data Center Only - This article only applies to Atlassian products on the Data Center platform.

Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible


This guide explains how to migrate or move your Smart Mirror installation in Bitbucket Data Center from one server to another.

(info) This is applicable only if the Mirror Base URL isn't changing during the migration if you plan to change the Mirror BASE_URL as part of the migration then the Mirror must be rebuilt from scratch as described on the KB Set up a mirror the same procedure applies for the Mirror Farm as well Set up and configure a mirror farm.

Currently, changing either the Mirror BASE_URL or the Primary/Upstream BASE_URL the mirror points to after the setup is not possible. The best course of action would be to recreate the Mirror or Mirror Farm using the new Primary/Upstream and Mirror URLs following the instructions from the above-shared links.

We currently have a Feature Request open to support the above-mentioned config changes


This applies to Bitbucket Data Center Smart Mirror/Mirror Farm installations running 6.7+, 7.x, 8.x


1. Prerequisites

Before you start Migrating the Mirror to a new server ensure the below criteria is met 

  • This procedure should only be followed if there are no changes to the Mirror BASE_URL or the Primary BASE_URL in the new Mirror server and you plan to use the same details on the new server.
  • Changing the Mirror BASE_URL or the Primary BASE_URL after migration requires the Mirror or Mirror Farm to be rebuilt from scratch and old data can't be used in that case. 

2. Migration Steps

  • Install the same version of Bitbucket Mirror on the new server as the one running on the old server.
  • On the new Mirror server, ensure that the $BITBUCKET_HOME environment variable points to the correct directory where the data will be copied from the old server.
  • (warning) It's crucial to completely stop both the old and new Bitbucket Mirror services before proceeding with the data transfer.
  • Copy or zip the entire $BITBUCKET_HOME from the old Mirror server and transfer it to the corresponding directory on the new Mirror server.
    • (info) This will ensure that the Mirror Internal H2 Database, the SSH keys used to connect the Mirror to the Primary, and Mesh Sidecar Config Info used on the Mirror Internally on the old server are all copied over to the new server.
  • After copying or unzipping $BITBUCKET_HOME on the new server, double-check that the Bitbucket Mirror or Mirror Farm installation points to the correct directory where the data has been transferred.
  • (warning) Before starting the Mirror, it is important to ensure that the DNS for the Mirror BASE_URL points to the new server and not the old one. This is to prevent any connectivity issues that may arise.
    • Also, if any Load Balancer/Reverse proxy needs to be updated to point to the new server IP, it must be done beforehand.
  • After verifying all configurations and setting up the new server with the same Bitbucket Mirror version and correct $BITBUCKET_HOME data, start the Bitbucket Mirror service.
  • This will start the Bitbucket Mirror Service, and the Mirror will get registered to the Primary/Upstream Server as expected.
  • After startup, the Mirror will perform a snapshot synchronization to sync all pending changes from the Primary to the Mirror during its offline period. This process ensures that repositories are up to date with the Primary/Upstream not synced from scratch.

If you encounter any issues with the new Mirror setup after the Migration, such as missing configurations or required files, carefully review whether all the above steps were followed correctly and reach out to our support team for further assistance if needed. 

Last modified on Apr 3, 2024

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.