Set up a mirror

Smart Mirroring

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

This feature is available for customers with an active Bitbucket Data Center license or a Premium account on Bitbucket Cloud. To try Smart Mirroring, obtain a Bitbucket Data Center evaluation license, or see Smart Mirroring for Bitbucket Cloud.

Smart Mirroring can drastically improve Git clone speeds for distributed teams working with large repositories. This page describes how to install a mirror and troubleshoot any issues you might encounter.

For an overview of the benefits to mirroring, see Smart Mirroring. For answers to frequently asked questions regarding mirroring, see Bitbucket Data Center FAQ. These instructions assume you already have a fully licensed Bitbucket Data Center instance up and running.

On this page

Before you start

You must also meet the following requirements:

  • Your primary Bitbucket instance must be a fully licensed Bitbucket Data Center instance - You do not actually have to run your Bitbucket Data Center instance as a multi-node cluster to use Mirroring, but you must have an up-to-date Data Center license.
  • The primary instance and all mirror(s) must have HTTPS with a valid (i.e., signed by a Certificate Authority anchored to the root and not expired) SSL certificate - This is a strict requirement of Smart Mirroring on both the primary instance and all mirror(s), and cannot be bypassed. The mirror setup wizard will not proceed if either the mirror or the primary instance does not have a valid SSL certificate.
  • The primary Bitbucket Server instance must have SSH enabled - Mirrors keep their repositories synchronized with the primary instance over SSH and can not use HTTP or HTTPS for this. See Enabling SSH access to Git repositories in Bitbucket Server for instructions on enabling SSH access on your primary instance.
  • The platform the mirror is running on must meet the same minimum requirements for Bitbucket Data Center - Check the Supported platforms for detailed requirements, including those for Java and Git, apply to each mirror.
  • The platform the mirror is running on must have the SSH client installed - The mirror will need an SSH client installed in order to fetch changes from the primary Bitbucket Server.
  • The platform the mirror is running on should not be under-provisioned - Just as with your primary Bitbucket Data Center instance, your mirrors need to be provisioned with enough CPU, memory, and I/O resources to handle their peak workload. See Scaling Bitbucket Server for more information. 
  • Minimum version Bitbucket 4.2 - Both the primary instance and mirror(s) must be running Bitbucket 4.2.0 or higher. (The primary and mirror(s) do not need to be identical versions, provided they are both 4.2.0 or higher.)
  • Running your mirror behind a reverse proxy server and terminating SSL at the proxy is highly recommended - See Proxying and securing Bitbucket Server.

1. Install Bitbucket on the mirror

The easy way to install a mirror is to download and run the Bitbucket installer and select the Install a new mirror option. (Note this is the same installer that you use for standard Bitbucket Server and Data Center instances, the mirroring functionality is included in the same distribution.) 

  1. Go to and download the latest version of the Bitbucket installer onto the server where the mirror will reside. 
  2. Run the installer, and be sure to select Install a new mirror.
  3. Complete the rest of the installation wizard.

Installing from an archive file

Alternatively, If you prefer not to use the Bitbucket installer, you can:

  1. Install Bitbucket Server from an archive file but do not start it.
  2. Add the following line to your ${BITBUCKET_HOME}/shared/


2. Set up HTTPS on the mirror

If you're configuring mirroring for Bitbucket Cloud, go to Set up Bitbucket Smart Mirroring instead.

You must configure your mirror to use HTTPS with a valid SSL certificate, and make secure access mandatory. 

SSL certificates are issued by a trusted third party Certificate Authority (CA), such as VeriSignDigiCert or Thawte, which provide such services on a commercial basis. Atlassian does not provide such services or support their use. 

Once you have an SSL certificate, you can configure your mirror to use it by following one of the options in Securing a reverse proxy using HTTPS.

You can choose whether to install your SSL certificate in a reverse proxy server or directly into Tomcat, either approach will work. But for performance, running your mirror behind a reverse proxy server such as nginx or HAproxy and terminating SSL at the proxy is highly recommended. See Proxying and securing Bitbucket Server for more information.

Both your mirror and your primary (upstream) instance must be configured for HTTPS. The mirror setup wizard will not proceed if either the mirror or the primary instance does not have a valid SSL certificate.

3. Start the mirror

Then start your mirror.


sudo service atlbitbucket start
See Starting and stopping Bitbucket Server for more information on starting and stopping mirrors with the service command.

4. Set up the mirror

Once your mirror has started, you can go to the setup wizard by navigating to https://<mirror-full-name> in your browser, where <mirror-full-name> is your mirror's fully qualified name in the DNS. This name will be pre-filled as the Mirror base URL and cannot be changed after you click Submit configuration, so make sure your primary Bitbucket instance is able to reach the mirror with this name. 

Descriptions of the fields:

Mirror nameThe human-readable name of the instance. Users will see this name when selecting a mirror to clone from.
Choose a name that your users will recognize and understand which name is the closest and fastest one for them.
Mirror base URLThe URL where the mirror can be accessed.
Primary server URLThe URL of the primary Bitbucket Data Center instance.

After configuring your details, click Submit configuration


The setup wizard fields cannot be changed after you click Submit configuration, so fill them in carefully. If you do make a mistake and need to change a mirror's setup after it has been submitted, you need to stop the mirror, delete its home directory completely, and go back to step 2, Set up SSL on the mirror.

Advanced: Automated setup

As an alternative to the setup wizard, you can automate the setup process without needing to navigate to the mirror in a browser. You can supply the <Mirror name>, <Mirror base URL>, and <Primary server URL> to your new mirror by adding the following properties to your ${BITBUCKET_HOME}/shared/ file. These properties can only be applied on the initial start of a new mirror, not after the mirror has already been set up.

setup.displayName=<Mirror name>
setup.baseUrl=<Mirror base URL>
plugin.mirroring.upstream.url=<Primary server URL>

This can be useful if you deploy new mirrors using an automated process such as Puppet. See Automated setup for Bitbucket Server for more information.

Once you have successfully set up your mirror, it will guide you to log in to the primary instance as an administrator to approve it. 

5. Approve a mirror request

Once a mirror has been installed and configured a request is sent to the primary Bitbucket Data Center instance. 

An approved mirror will have access to all projects and repositories in the primary Bitbucket Data Center instance. Smart Mirroring has been designed to require secure communication throughout and restrict all functionality to the appropriate privilege level (e.g., system administrator) to ensure the security of all your sensitive information. It is still your responsibility to set up mirrors with the same stringent security practices as your primary Bitbucket Data Center instance. See the FAQ How secure is Smart Mirroring? for more information.

To approve a mirror request

  1. Within the primary Bitbucket Data Center instance, go to Admin > Mirrors, and you will see the name of the mirror and that approval is required.

  2. Click Approve to approve the mirror request and start syncing the projects and repositories of the primary Bitbucket Data Center instance.

6. Decide which projects to mirror

Once a mirror instance is approved you need to decide which projects to mirror. Go to Admin > Mirrors and type in the name of a project in the search box. Do this for each projects you want to mirror. You can also choose to mirror all projects.

Mirroring all projects cannot be undone later

If you decide you do not want to mirror a project in the future you will have to completely remove and reinstall the mirror instance.




This section contains guidance on troubleshooting problems with installing a mirror. For further reference, read the Bitbucket Data Center FAQ, which covers the most frequently asked questions about Bitbucket Data Center.

No valid HTTPS configuration

  • Your primary Bitbucket Data Center instance and the mirror server must be configured for HTTPS access in order to use a mirror instance. See Proxying and securing Bitbucket Server for more information.
  • The value for the Primary server URL field must include the "https://" prefix.

Synchronizing projects stays stuck on "Retrieving project information..."

Incorrectly set Mirror base URL

  • The property Mirror base URL can only be set once. If configured incorrectly you will need to delete your mirror and set it up again.

Last modified on Feb 6, 2019

Was this helpful?

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