Set up a mirror
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.
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 have to run your Bitbucket Data Center instance as a multi-node cluster to use smart 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 instance must have SSH enabled - Mirrors keep their repositories synchronized with the primary instance over SSH and cannot use HTTP or HTTPS for this. See Enable SSH access to Git repositories for instructions on enabling SSH access on your primary instance.
- Each mirror is considered a unique Bitbucket instance - Home directories of mirrors should not be shared with the upstream or with other mirrors.
The platform the mirrors are 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, that apply to each mirror.
- By design, each mirror (standalone or in a mirror farm) must run with an internal H2 database - Using an external database is highly discouraged for mirrors and will compromise performance significantly.
The platform the mirrors are running on must have an OpenSSH client installed - The mirror will need an OpenSSH client installed to fetch changes from the primary Bitbucket Server.
If you are using Bitbucket version 7.9 or higher, then you must use OpenSSH version 7.2 or higher to avoid sync failures for repositories.
The platform the mirrors are 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 Data Center for more information.
- Running your mirror behind a reverse proxy server and terminating SSL at the proxy is highly recommended - See Proxy and secure Bitbucket.
- The ports of communication between the primary instance and the mirror should be opened - The mirror host should be able to connect the primary on HTTPS (443) and SSH (7999) ports. Also, the primary needs to reach the mirror on the HTTPS (443) port.
1. Install Bitbucket on the mirror
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.
Go to Download Bitbucket Data Center and download the latest version of the Bitbucket installer to the server where the mirror will run.
Run the installer, and be sure to select Install a new mirror.
- Complete the rest of the installation wizard.
Installing from an archive file
Alternatively, If you prefer not to use the Bitbucket installer, you can:
- Install Bitbucket Data Center from an archive file but do not start it.
Add the following line to your
${BITBUCKET_HOME}/shared/bitbucket.properties:application.mode=mirror
2. Set up HTTPS on the mirror
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 VeriSign, DigiCert 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 Proxy and secure Bitbucket 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
sudo service atlbitbucket startservice 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 name | The 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 URL | The URL where the mirror can be accessed. |
| Primary server URL | The 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/bitbucket.properties 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>
plugin.mirroring.upstream.type=serverThis can be useful if you deploy new mirrors using an automated process such as Puppet. See Automated setup for Bitbucket for more information.
Once you have successfully set up your mirror, it will guide you to log into 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
In your primary Bitbucket Data Center instance, go to Admin > Mirrors. The authorization request will appear.
- Click Authorize 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 project you want to mirror. You can also choose to mirror all projects.
If you choose to mirror all projects, you will not be able to select individual projects. This can't be undone. If you decide you no longer want to mirror all projects, you'll need to completely remove and then reinstall the mirror.
Troubleshooting
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 Proxy and secure Bitbucket for more information.
- The value for the
Primary server URLfield must include the "https://" prefix.
Synchronizing projects stays stuck on "Retrieving project information..."
- Ensure SSH is enabled and usable on the primary instance. See Enable SSH access to Git repositories.
- Ensure your SSH base URL is set correctly in Server settings on the primary instance. See Enable SSH access to Git repositories.
- If appropriate, see Setting up SSH port forwarding.
Incorrectly set Mirror base URL
The property
Mirror base URLcan only be set once. If configured incorrectly you will need to delete your mirror and set it up again.
"No response was received from the URL you entered" when adding an application link to Bitbucket
Currently, when Bamboo connects to a Bitbucket Data Center instance, it uses the Base URL to perform any Git operations. To make the URL available also for mirrored instances, you must use the Generic Git for mirrored repositories.