Set up and configure Mesh nodes
A Data Center license is required to use this feature. Get an evaluation license to try it out, or purchase a license now.
Bitbucket Mesh allows you to set up a group of nodes that work as distributed, replicated, and horizontally scalable Git repository storage for Bitbucket Data Center. This page shows you how to install and configure Mesh nodes and connect them to your Bitbucket Data Center instance.
For an overview of the benefits of using Bitbucket Mesh and how moving Git repositories to Mesh nodes can help your organization, see Bitbucket Mesh.
On this page
Before you attempt to set up and configure Mesh nodes, make sure you’ve noted the considerations and completed all the prerequisites described in this section.
We recommend that you use Network Time Protocol (NTP) to synchronize the time on all nodes and keep clocks in sync. Also, while Mesh nodes can be in different locations, they require a fast, low latency connection to each other.
Prerequisites and system requirements
- Your primary Bitbucket instance is a fully licensed Bitbucket Data Center instance – You don’t need to run your Bitbucket Data Center instance as a multi-node cluster to use Bitbucket Mesh, but you must have an up-to-date Data Center license.
- You have the minimum version of Bitbucket 8.0 – The versions of the Bitbucket instance and Mesh nodes are independent of each other; however, the minimum version of Bitbucket that supports Mesh is 8.0.
- You have a separate home directory for each Mesh node – You’ll be configuring multiple Bitbucket Mesh nodes and as each node is unique they should not use a shared storage for their home directory. Do not share the home directories of the Mesh nodes with the Bitbucket Data Center instance or with other Mesh nodes.
- You’ve installed a minimum version of Git 2.31 on your Bitbucket Data Center instance and the Mesh nodes – For more details, see Supported platforms.
- You have the same platform on all your Mesh nodes - For more details, see Supported platforms, including those for Java and Git, which apply to each Mesh node.
- The platform that the Mesh nodes are running on have sufficient provisioning – Just as your primary Bitbucket Data Center instance, your Mesh nodes need to be provisioned with enough CPU, memory, and I/O resources to handle their peak workload. We recommend that Mesh nodes be sized similar to the your Bitbucket Data Center instance. Learn more about Mesh requirements
Installing and starting a Bitbucket Mesh node
Once you've added a Mesh node, you can't remove it. If you need to remove a Mesh node, contact support.
1. Download Bitbucket Mesh
Refer to the compatibility matrix and download the compatible version of Mesh that suits your Bitbucket version.
- Create your installation directory (with full control permission) on the Mesh node – this is where Bitbucket Mesh installation files will be stored. Avoid using spaces or special characters in the path. We'll refer to this directory as your
<installation-directory>in the below steps.
- Extract the Mesh
.zipfile you've downloaded to your
3. Create the Mesh home directory
- Create your home directory (with full control permission) on the Mesh node – your Bitbucket Mesh data will be stored here. Note that this should be separate to your installation directory. We'll refer to this directory as your
<home-directory>in the below steps.
<installation-directory>/bin/set-mesh-home.shfile – uncomment the
MESH_HOMEline and add the absolute path to your home directory.
4. (Optional) Configure SSL
Depending on your security requirements, you may want to encrypt the communications between Bitbucket Server and Mesh. If the network between Bitbucket Server and Mesh is fully trusted, you can skip this step.
Bitbucket Server communicates with Mesh over gRPC. To configure Mesh to expose its gRPC services over HTTPS:
Generate/obtain a private key and certificate chain file for the SSL certificate that Mesh should use. The certificate must be signed by a trusted Certificate Authority (CA) such as Let’s Encrypt, VeriSign, DigiCert or Thawte. If your Certificate Authority provides you with an intermediate certificate, you can create a
.pemfile containing the full certificate chain by appending the intermediate certificate to the certificate that receive from your Certificate Authority.
-----BEGIN CERTIFICATE----- (Your Primary SSL certificate: your_domain_name.crt) -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- (Your Intermediate certificate: intermediate.crt) -----END CERTIFICATE-----
- Copy the certificate and private key file to a directory that Mesh can access, for example,
mkdir -p <mesh-home>/config/ssl cp key.pem cert.pem <mesh-home>/config/ssl
<mesh-home>/mesh.propertiesfile with the following contents:
5. (Optional) Customize Mesh configuration
If you need to change the port Mesh will run on, or some other Mesh configuration, you can create or edit
<mesh-home>/mesh.properties to customize the configuration.
6. Start Bitbucket Mesh
Change directory to the <installation-directory> and run the below command:
Observe the logs and confirm that Bitbucket Mesh has started successfully. You should see something similar to below:
2022-03-11 08:56:42,170 INFO [main] - c.a.bitbucket.mesh.grpc.GrpcServer gRPC server started (port: 7777, SSL: false, maxDirectMemory: 7029 MB) 2022-03-11 08:56:42,175 INFO [main] - c.a.b.mesh.boot.MeshApplication Started MeshApplication in 3.085 seconds (JVM running for 3.732) 2022-03-11 08:56:42,177 INFO [main] - c.a.b.mesh.boot.StandaloneRunner Ready to serve
Connecting the Mesh node to Bitbucket
Once Bitbucket Mesh has started, you can connect it to your Bitbucket Data Center instance.
To connect the mesh node:
- In your Bitbucket Data Center instance, navigate to Administration > Git > Bitbucket Mesh.
- Enter the URL of the Mesh node you’ve created earlier in the Node URL field. If you’ve secured communications between Bitbucket Server and Mesh, make sure you use https here.
- (Optional) Enter a name for the Mesh node in the Node name field.
- Select Add Mesh node.
You’ve now successfully added a Mesh node to your Bitbucket Data Center instance. Once you’ve connected at least 3 Mesh nodes, you can migrate your Git repositories to Mesh.