Bitbucket Data Center upgrade guide
Plan your upgrade
1. Determine your upgrade path
You can update from any previous version of Bitbucket Data Center to the latest version, as there is no required upgrade path.
If you are upgrading a multi-node Bitbucket cluster to the next bug fix update (for example, from 10.0.0 to 10.0.1), you can upgrade with no downtime.
Bitbucket Data Center 10.x is a major upgrade
If you’re upgrading from Bitbucket 8.x or 9.x, be sure to read the Bitbucket 10.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 10.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 10.x before upgrading.
Bitbucket 10 does not include a bundled OpenSearch server
Starting with Bitbucket 10.0, OpenSearch is no longer bundled with Bitbucket.
If you run a single-node Bitbucket installation that uses bundled search, you now need to set up and connect your own remote OpenSearch server.
Clustered systems were already required to use an external OpenSearch instance, so this change should not affect them.
Review migration steps for OpenSearch
Changes in Mesh configuration properties
If you are monitoring your Mesh nodes with an external system (like SignalFx or Datadog), the management.* properties used to configure metrics publishing have changed slightly. For instance, the property management.metrics.export.datadog.enabled is now management.datadog.metrics.export.enabled. The Mesh configuration properties page includes a full list of all management.* properties.
2. Complete pre-upgrade checks
- Check the Version specific upgrade notes for the version you plan to upgrade to (and any in between).
- Go to Administration and select Support Tools. Then, review the Log analyzer for any issues that may need to be resolved.
Check the compatibility of your apps with the version you plan to upgrade to.
- Go to Administration and select Manage apps. Then, select Bitbucket update check.
Choose the version you plan to upgrade to. Then, select Check.
3. Upgrade Bitbucket in a test environment
- Create a staging copy of your current production environment.
- Follow the steps below to upgrade your test environment.
- 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+. Bitbucket 8.x mirrors are incompatible with Bitbucket 9.0+.
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.
If upgrading to 9.4.2+ or 9.5.0+ and you’ve previously configured logging.debug.enabled or logging.profiling.enabled in the config properties of your mirrors, we recommend removing those config properties. Debug logging and profiling settings can instead be dynamically enabled through REST:
BSERV-19782 - Getting issue details... STATUS
Alternatively, you can enable these settings through the user interface, provided that both the farm and upstream node are running on version 9.5.0+.
To upgrade a mirror or mirror farm:
Stop all nodes in a mirror farm, or the only node if it's a standalone mirror.
Stop the primary instance.
Upgrade the primary instance and wait for it to start up properly.
Go to the Mirrors page and verify that no mirrors exist.
Upgrade all mirror instances one by one.
On the Mirrors page, wait for the pre-existing mirrors to show up with the Awaiting authorization status.
Authorize the mirrors and verify all the nodes acquire the Online status.
Upgrade Bitbucket Data Center
1. Back up your data
Determine which backup strategy to use.
- Back up all the data in your Bitbucket home directory and external database.
2. Stop the system
Before upgrading, you must stop all the nodes in the cluster before upgrading. For more info, see Starting and stopping Bitbucket.
If you’re using a load balancer, 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 from the Bitbucket Data Center Download Archives.
4. Upgrade the nodes
- Extract the files to a directory. This will be your new installation directory, and and it must be different from your existing installation directory.
Update the value of BITBUCKET_HOME in the
<Installation-directory>/bin/set-bitbucket-home.shfile 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.
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
- Start Bitbucket on the node. Learn more about starting Bitbucket
- Repeat steps 1 through to 4 to install Bitbucket on the remaining nodes.
5. Start Bitbucket and check cluster connectivity
Once all nodes have been upgraded, you can start Bitbucket Data Center.
If you have a cluster, you should start 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 can check the details of each node.