How to re-install/re-register a single Bitbucket Smart Mirror
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
Summary
After experiencing an issue with a Bitbucket Smart Mirror, at times it may be appropriate to remove the existing data/configuration on the mirror and attempt re-registering it with the upstream server.
As mirrors are read-only, the process for resetting a mirror is non-destructive and can be accomplished fairly quickly - with the largest wait time only being the initial synchronization of the desired repositories back to the mirror after completing the steps below.
Environment
Bitbucket Data Center
Individual smart mirror(s) in use
Solution
All of the steps below (except for the first and last step) are applicable only to the mirror server.
None of these steps relating to the Bitbucket home should be performed on the upstream/primary Bitbucket instance.
Delete the mirror connection on the front-end of the primary/upstream Bitbucket instance by navigating to Administration → Mirrors → <Mirror Name> → Delete
Stop the service of the mirror on the mirror server
On the filesystem of the mirror, navigate to the "$BITBUCKET_HOME/shared" directory and move/backup the config directory.
ℹ️ The data directory is safe to delete, as the data there is just a copy of what's on the upstream. The config directory, though, can contain the Java Keystore being used by the mirror as well as the SSH Host key used for identifying the mirror to SSH clients - so we recommend backing that directory up.
ℹ️ Skipping the deletion of the `
ssl-keystore` is applicable only if the Mirror is configured with SSL on the Mirror's Tomcat Application Server itself.If SSL is configured on the Load Balancer or Reverse Proxy, then you might not have the `
ssl-keystore` file in your Bitbucket Home directory.
After backing up the config directory, delete the following data/config directories on the mirror:
$BITBUCKET_HOME/shared/data$BITBUCKET_HOME/shared/configℹ️ Using a command like the following can help retain the
ssl-keystorefile and SSH Host key mentioned in the previous step:1find ./config -not -name 'ssl-keystore' -not -name 'ssh-server-keys.pem' -delete
Create a
${BITBUCKET_HOME}/shared/bitbucket.propertiesfile and set the below property to start the instance as Mirror1application.mode=mirror
Start the mirror, and go through the setup screen to re-add it to the primary Bitbucket instance.
On the upstream, navigate to the mirror and add the desired projects to be mirrored.
Once the projects have completed their initial synchronization, you should be good to go!
Otherwise, if you continue to experience issues with your mirror - it's recommended that your team review our mirror troubleshooting guide or reach out to our support team for further assistance.
Was this helpful?