Summary

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

This is applicable only if the Mirror Base URL isn't changing during the migration if you plan to change the Mirror or Mirror Farm 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 or Mirror Farm BASE_URL or the Primary/Upstream BASE_URL the mirror points to after the initial 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 KB articles.

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

• BSERV-12942 - Getting issue details... STATUS
• BSERV-12882 - Getting issue details... STATUS

Environment

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

Solution

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 or Mirror Farm 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 or Mirror Farm 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.
• 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.
  • 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.
• Before starting the Mirror, it is important to ensure that the DNS for the Mirror or Mirror Farm 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.