Upgrade Bitbucket Data Center

Still need help?

The Atlassian Community is here for you.

Ask the community

This page contains instructions for upgrading an existing Bitbucket cluster.

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.

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 read the End of support announcements for Bitbucket Server

You can update from any previous version of Bitbucket Server (or Stash) to the latest version, as there is no required upgrade path.

Bitbucket 6 is a major upgrade

Be sure to read the Bitbucket Server 6.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 6 disables all user-installed apps on startup

Be sure to update your own apps and check the Atlassian Marketplace to ensure 3rd-party apps are compatible with Bitbucket Server 6 before upgrading.

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 > 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 > Manage apps > Bitbucket update check.

    2. Choose the version you plan to upgrade to then click Check.

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.

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 BackupDIY Backup, or take snapshots of the shared home directory (on NFS) and database while all nodes are stopped. 

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

  2. Back up the following directories:

    • Installation directory on every node

    • Local home directory on every node

    • Shared home directory

    • External database

2. Migrate customizations

Bitbucket 5.0 changed where custom server configurations are kept. Previously, Tomcat container customizations were made in the server.xml file, located in either the <Bitbucket home directory>/shared directory (from 3.8 to 4.14), or in <Stash installation directory>/conf (for 3.7 and earlier). 

  1. First, determine if you've made customizations to your server.xml file. You would have made these changes if you modified the portcontext path, or the Proxying and securing Bitbucket Server, or if you are running Bitbucket Server behind a proxy and modified the Connector element.

  2. Migrate changes in the bitbucket.properties file in your existing Bitbucket home directory. The bitbucket.properites file uses a slightly different syntax, so it is not merely a copy and paste procedure.
    Read the page Migrate customizations from server.xml to bitbucket.properties and follow the instructions to migrate your customizations. 

    For custom configurations in Bitbucket Data Center...

    Bitbucket Data Center instances on version 3.8 or later, the single server.xml file in the <Bitbucket home directory>/shared directory replaces all the copies of server.xml located in the <Bitbucket installation directory>/conf directories of the cluster nodes using previous versions of Bitbucket Server (or Stash).

3. 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 Confluence until the upgrade is complete on all nodes.

4. Download Bitbucket

Download the appropriate file for your operating system - https://www.atlassian.com/software/bitbucket/download-archives.

5. Upgrade the first node

To upgrade the first node:

  1. Extract (unzip) the files to a directory (this will be your new installation directory, and must be different to your existing installation directory)

  2. Update the value of BITBUCKET_HOME in the <install-directory>/bin/set-bitbucket-home.sh (or set-bitbucket-home.bat on Windows) file so the new Bitbucket Server installation points to your existing Bitbucket Server home directory (if you use a BITBUCKET_HOME environment variable to specify the home directory location, no change is required).

  3. Copy the database driver from your existing Bitbucket installation directory to the new one.

  4. Copy any other immediately required customizations from the old version to the new one (for example if you are not running Bitbucket on the default ports or if you manage users externally, you'll need to update / copy the relevant files)

  5. Start Bitbucket, and confirm that everything works as expected.

If you haven’t reapplied all customization from the old version, you should do it now, so you copy them along with the whole installation directory to remaining nodes.

6. 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 (or set-bitbucket-home.bat on Windows) 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. 

7. 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 (AdministrationSettings > Clustering) includes information about the active cluster nodes. When the cluster is running properly, you should be able to see the details of each node. 

Last modified on Mar 2, 2020

Was this helpful?

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