Bitbucket Data Center upgrade guide

Upgrade guidelines in Bitbucket

On this page

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

This page contains instructions for upgrading an existing Bitbucket cluster to the next major or minor version. Upgrading to either version type will incur downtime. 

If you are not running Bitbucket in a cluster, follow the instructions in Bitbucket Server upgrade guide.

Upgrading to any later version is free if you have current software maintenance. See our Licensing FAQ to find out more.

If you deployed Bitbucket Data Center on AWS using our AWS Quick Starts, refer to the Upgrading section of Administer Bitbucket Data Center in AWS instead.

On this page:

IMPORTANT Platform releases allow us to incorporate multiple significant changes (often called “breaking changes”) that aren't compatible with previous versions. These changes establish a strong foundation for more extensive development in future releases.

To increase security and performance, we’ve made changes in our core architecture that require apps to bundle their libraries. We're collaborating with our Marketplace partners on these changes, however, some apps may not be immediately compatible with the new platform upon release.

We recommend that you review your apps before upgrading to reduce the risk of disruption for your organization.

To check app compatibility, visit Checking app compatibility with application updates, or the Atlassian Marketplace to see if your app hosting is compatible with your product version.

Plan your upgrade

1. Determine your upgrade path

Check the Supported platforms page to determine if your environment meets the minimum requirements to run the latest version of Bitbucket. Also, check the End of support announcements. 

You can update from any previous version of Bitbucket Data Center to the latest version, as there is no required upgrade path. If you’re upgrading from Bitbucket Server to the Data Center-only version, check the guide on how to do this: Upgrade from Bitbucket Server to Bitbucket Data Center.

Bitbucket Data Center 9.x is a major upgrade

Be sure to read the Bitbucket 9.0 release notes, take a full backup, and test your upgrade in a non-production environment before upgrading your production site.

Upgrading from a version older than Bitbucket 9.x disables all user-installed apps on startup

Be sure to update your own apps and check the Atlassian Marketplace to ensure third-party apps are compatible with Bitbucket Data Center 9.x before upgrading.

tip/resting Created with Sketch.

Upgrading to the next bug fix update

If you are upgrading a multi-node Bitbucket cluster to the next bug fix update (for example, from 9.0.0 to 9.0.1), you can upgrade with no downtime.

2. Complete pre-upgrade checks

  1. Check the Version specific upgrade notes for the version you plan to upgrade to (and any in between).
  2. Go to Administration and select Support Tools. Then, review the Log analyzer for any issues that may need to be resolved.

  3. Check the compatibility of your apps with the version you plan to upgrade to.

    1. Go to Administration and select Manage apps. Then, select Bitbucket update check.

    2. Choose the version you plan to upgrade to. Then, select Check.

      If you have incompatible apps

      If your users rely on particular apps, you may want to wait until they are compatible before upgrading Bitbucket. App vendors generally update their apps very soon after a major release.

      Good to know:

      • If you're performing a major version upgrade, user-installed apps will be disabled. You will need to enable your apps after successfully upgrading, regardless of compatibility with Bitbucket.

      • You can disable an app temporarily if it is not yet compatible. 

3. Upgrade Bitbucket in a test environment

  1. Create a staging copy of your current production environment.
  2. Follow the steps below to upgrade your test environment.
  3. Test any unsupported apps, customizations and proxy configuration (if possible) before upgrading your production environment.

4. Upgrade Bitbucket mirrors

If you’re using mirrors, make sure you upgrade both your primary instance and mirrors to Bitbucket 9.0. Otherwise, mirrors won’t work in the new version.

We recommend that you take the following steps to upgrade the primary instance and mirrors.

If you follow a custom upgrade procedure, be aware that you may encounter errors that will be displayed in the logs. To avoid errors, follow the provided guidelines.

To upgrade a mirror or mirror farm:

  1. Stop all nodes in a mirror farm, or the only node if it's a standalone mirror.

  2. Stop the primary instance.

  3. Upgrade the primary instance and wait for it to start up properly.

  4. Go to the Mirrors page and verify that no mirrors exist.

  5. Upgrade all mirror instances one by one.

  6. On the Mirrors page, wait for the pre-existing mirrors to show up with the Awaiting authorization status.

  7. Authorize the mirrors and verify all the nodes acquire the Synchronized status.

Upgrade Bitbucket Data Center

1. Back up your data

  1. Determine which backup strategy to use. 

    Summary of the different backup strategies for Bitbucket...

    For Bitbucket Data Center (version 4.8 or later) instances, you can use Zero Downtime Backup, DIY Backup, or take snapshots of the shared home directory (on NFS) and database while all nodes are stopped. 

    For Bitbucket mirrors, the home directory doesn't store any persistent state that can't be reconstructed from the primary Bitbucket instance, but you should still make sure you have a backup of at least the important configuration files such as SSL certificate, server.xml,  config/ssh-server-keys.pem,  bitbucket.properties file, and so on in a safe place. See  How do I back up my mirrors? for more information.

    See the article Data recovery and backups for detailed information and guidance on creating an effective backup strategy.

  2. Back up all the data in your Bitbucket home directory and external database.

2. Stop the cluster

You must stop all the nodes in the cluster before upgrading. For more info, see Starting and stopping Bitbucket.

We recommend configuring your load balancer to redirect traffic away from Bitbucket until the upgrade is complete on all nodes.

3. Download Bitbucket

Download the appropriate file for your operating system on Bitbucket Server & Data Center Download Archives.

4. Upgrade the first node

To upgrade the first node:
  1. Extract the files to a directory. This will be your new installation directory and it must be different from your existing installation directory.

  2. Update the value of BITBUCKET_HOME in the <Installation-directory>/bin/set-bitbucket-home.sh file so the new Bitbucket installation points to your existing Bitbucket home directory.

    If you’re using a BITBUCKET_HOME environment variable to specify the home directory location, no change is required.

  3. Copy any other immediately required customizations from the old version to the new one. For example, if you aren’t running Bitbucket on the default ports or if you’re managing users externally, you'll need to update or copy the relevant files.

    If you’ve configured Bitbucket to run as a Linux service, don't forget to update its service configuration as well. Learn more about running Bitbucket as a Linux service

  4. Start Bitbucket on the node. Learn more about starting Bitbucket

Why doesn’t Bitbucket search work after the upgrade?

When you’re starting up your Bitbucket Data Center instance after the upgrade, the bundled search server won’t run. Instead, the remote search will be started.

This happens because Data Center instances use the remote search, not the bundled search.

During the upgrade, the --no-search flag is inserted in the /etc/init.d/atlbitbucket file. This flag allows running the remote search but blocks the bundled search.

5. Copy Bitbucket to remaining nodes

The next step is to replicate your upgraded Bitbucket directories to other nodes in the cluster.  

  1. Stop Bitbucket on the first node.

  2. Copy the installation directory and local home directory from the first node to the next node. 
    If the path to the local home directory is different on this node, edit the /bin/set-bitbucket-home.sh to point to the correct location. 

  3. Start Bitbucket and confirm that everything works as expected.

  4. Stop Bitbucket on this node before continuing with the next node. 

Repeat this process for each remaining node. 

6. Start Bitbucket and check cluster connectivity 

Once all nodes have been upgraded, you can start Bitbucket Data Center on each node, one at a time. Starting up multiple nodes simultaneously can lead to serious failures.

The Cluster monitoring console under Administration, Settings, Clustering includes information about the active cluster nodes. When the cluster is running properly, you'll be able to check the details of each node. 

Last modified on Jun 18, 2024

Was this helpful?

Yes
No
Provide feedback about this article

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.