Set up and configure Mesh nodes

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 start

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

Make sure that:

  • 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.9 and Mesh 2.0 – The versions of the Bitbucket instance and Mesh nodes are independent of each other; however, each Bitbucket version is compatible with a specific Mesh version.
  • 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

1. Download Bitbucket Mesh

Refer to the compatibility matrix and download the compatible version of Mesh that suits your Bitbucket version.

2. Create the installation directory

  1. 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.
  2. Extract the Mesh .zip file you've downloaded to your <installation-directory>.

3. Create the Mesh home directory

  1. 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.
  2. Edit <installation-directory>/bin/set-mesh-home.sh file – uncomment the MESH_HOME line 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 Data Center and Mesh. If the network between Bitbucket Data Center and Mesh is fully trusted, you can skip this step.

Bitbucket Data Center communicates with Mesh over gRPC. To configure Mesh to expose its gRPC services over HTTPS:

  1. 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 .pem file 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-----
  2. Copy the certificate and private key file to a directory that Mesh can access, for example, <mesh-home>/config/ssl
    mkdir -p <mesh-home>/config/ssl
    cp key.pem cert.pem <mesh-home>/config/ssl
  3. Create a <mesh-home>/mesh.properties file with the following contents: 

    grpc.server.ssl.cert-chain-path=<mesh-home>/config/ssl/cert.pem
    grpc.server.ssl.private-key-path=<mesh-home>/config/ssl/key.pem

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

  1. Change directory to the <installation-directory> and run the below command: 

    bin/start-mesh.sh
  2. 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:

  1. In your Bitbucket Data Center instance, navigate to Administration > Git > Bitbucket Mesh.
  2. Enter the URL of the Mesh node you’ve created earlier in the Node URL field. If you’ve secured communications between Bitbucket Data Center and Mesh, make sure you use https here.
  3. (Optional) Enter a name for the Mesh node in the Node name field.
  4. 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.

Restarting the Mesh node

To restart the Mesh node:

  1. Disable the Mesh node through the user interface or REST API.
  2. Stop the Mesh node.
  3. Start the Mesh node.
  4. Enable the Mesh node through the user interface or REST API.

Removing a Mesh node

Before you take out a Mesh node:

  • note that you can remove a Mesh node only if you have more than 3 nodes. If you need to replace a node, add a new node first
  • make sure that the other Mesh nodes have enought disk space to host the data from the Mesh node you're removing

To remove a Mesh node:

  1. In your Bitbucket Data Center instance, navigate to Administration > Git > Bitbucket Mesh.
  2. Select Delete.

The node will remain in deleting state until all the data has been moved to the other Mesh nodes before it disappears.

Last modified on May 15, 2024

Was this helpful?

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