Set up and configure a mirror farm
Mirror farms allows you to set up a cluster of mirrors to cover the load in a local region. This page walks you through how to install and configure a mirror farm. Included are requirements you should meet before starting as well as the information you'll need for your load balancer configuration.
On this page
Before you start
We recommend you use real-time synchronization on all mirrors to keep clocks in sync. Also, while mirror farms can be in different locations, they must be able to talk to their peers quickly.
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.
Your mirror farm has to be accessible over HTTPS with a valid certificate. This configuration uses the same properties as the primary Bitbucket instance. See Proxy and secure Bitbucket.
You should have one dedicated load balancer per mirror farm. Running your mirrors behind a load balancer is necessary and terminating SSL at the proxy is highly recommended. See Proxy and secure Bitbucket.
You need to have set up a host name for your mirror farm (this relates to the load balancer and the SSL certificate). This is so users can connect to the mirror farm. Configurations for your mirror farm and load balancer must be in sync, having the same hostname.
- Each node of a mirror farm is considered unique - While there is some internode communication in a mirror farm, nodes of a single mirror farm should not use shared storage for their home directory.
- It is recommended that each node has its home directory on a local disk as opposed to having it on a shared NFS store.
- Home directories of mirrors should not be shared with the upstream or with other mirror farms.
The primary Bitbucket Data Center instance must have SSH enabled.
You must have a minimum version of Git 2.11.1 installed. See Supported platforms for more details.
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.
- Minimum version of Bitbucket - The primary instance and mirrors do not need to be running identical Bitbucket versions, but a mirror running Bitbucket 6.7 or later, can only point to a primary running Bitbucket 6.7 or later. An existing mirror running Bitbucket 6.6 or earlier can point to a primary running any supported Bitbucket version. These details are shown in the table below:
| Mirror | Primary instance |
|---|---|
| Bitbucket 6.7 or above | Bitbucket 6.7 or above (does not have to match the mirror's version) |
| Bitbucket 6.6 or below | Any supported version of Bitbucket that supports smart mirrors. |
1. Set up the load balancer for your mirror farm
Your load balancer must:
run on a dedicated machine
have a high-speed LAN connection to the Bitbucket cluster nodes (that is, high bandwidth and low latency)
support both HTTPS (for web traffic) and TCP (for SSH traffic)
use HTTPS with a valid SSL certificate (signed by a Certificate Authority anchored to the root and not expired)
have the mirrors running behind it all belong to the same mirror farm
You can use either a load balancer that supports session affinity ("sticky sessions") using the
BITBUCKETSESSIONIDcookie or you can set thehazelcast.http.sessions=replicatedand sticky sessions are not required.
We also recommend that you terminate SSL (HTTPS) at your load balancer and use a HTTP connection from the load balancer to Bitbucket for better performance.
For more details on installing and configuring your load balancer, head to the Install Bitbucket Data Center page. If you don't have a preference for your load balancer, we also provide instructions here for haproxy, a popular open source software load balancer.
2. Install Bitbucket on the mirror node
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 www.atlassian.com/software/bitbucket/download and download the latest version of the Bitbucket installer.
Run the installer, and be sure to select Install a new mirror.
- Do not start Bitbucket.
- Add the following properties to your
${BITBUCKET_HOME}/shared/bitbucket.properties file:
application.mode=mirror
setup.displayName=<Mirror name>
setup.baseUrl=<Mirror base URL>
plugin.mirroring.upstream.url=<Primary server URL> 5. Configure Hazelcast so that your mirror nodes talk to one another. For details, follow the instructions in the step, 4. Start the first cluster node in the Install Bitbucket Data Center page.
6. To add additional mirror nodes, repeat the above steps for installing a new mirror. There is no need to authorize the additional mirrors on your primary (upstream) instance if the properties match.
3. Start the mirror
Start your mirror:
sudo service atlbitbucket startSee Start and stop Bitbucket for more information on starting and stopping mirrors with the service command.
4. Approve the mirror farm request
Once a mirror farm has been installed and configured, a request is sent to the primary Bitbucket Data Center instance. From this page, it’s recommended that you verify the mirror farm ID against the one displayed at the mirror’s base URL.
To approve a mirror farm request:
In your primary Bitbucket Data Center instance, go to Admin > Mirrors.
Click Authorize to approve the mirror request and start syncing the projects and repositories of the primary Bitbucket Data Center Instance.
If the authorization request is declined, you’ll return to the Mirrors page and there will be no pending mirror.
If the properties of additional mirrors don't match, it could stop your farm from starting. The new mirror could also start its own farm if it can't find other mirrors.
An approved mirror farm 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 to restrict all functionality to the appropriate privilege level (such as 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.
5. Decide which projects to mirror
Once a mirror farm is approved, you need to decide which projects to mirror. In the Admin > Mirrors page, type in the name of a project in the search box. Do this for each project you want to add. 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.
For further reference and troubleshooting, read the Bitbucket Data Center FAQ, which covers the most frequently asked questions about Bitbucket Data Center.