Cloud
Data Center 8.11
Versions

Bitbucket Server upgrade guide

Install or upgrade Bitbucket

On this page

In this section

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

This guide describes how to upgrade your Bitbucket Server installation on Linux to the latest version using the installer.

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


Other ways to upgrade Bitbucket:

On this page:

Before you begin

Before you upgrade Bitbucket there are a few questions you need to answer.

Is using the installer the right upgrade method for you?
Tell me more...

You can choose to upgrade using the installer, or, if the installer is not suitable for your situation you can use an archive file to update your Bitbucket Server instance. Only use an archive file to update Bitbucket Server if the installer is not suitable for your situation, as the installer is the the recommended approach to upgrade for most use cases.

Read about how to upgrade Bitbucket Server from an archive file.

Are you eligible to upgrade?
Tell me more...

To check if software maintenance is current for your license, go to > Licensing and make sure the license support period has not expired.

If your support period has expired, follow the prompts to renew your license and reapply it before upgrading.

Have our support platforms changed?
Tell me more...

Check the Supported platforms page for the version of Bitbucket you are upgrading to. This will give you info on supported operating systems, databases and browsers.

Have you taken into consideration all the version-specific upgrade information?

Make sure you read the following pages for each version between your current version of the application and the version you're upgrading to:

This will give you information about specific update notes for each version of Bitbucket Data Center and Server.

Are you upgrading from Bitbucket 4.x or earlier and have you modified your server.xml file?
Tell me more...

In Bitbucket 5 we changed where you configure properties such as port numbers, context paths, and access protocol (among other things) to centralize custom configuration to a single directory and file, and to make upgrading easier for future releases.

Upgrading from any version earlier than or including Bitbucket Server 4.14 to Bitbucket Server 5.0 or later requires that you manually migrate any changes to the server.xml file to the bitbucket.properties file.

See the page Migrate customizations from server.xml to bitbucket.properties for instructions on locating your server.xml file and how to migrate your customizations.

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. 

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

Bitbucket 8 is a major upgrade

Be sure to read the Bitbucket Server 8.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 8 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 8 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 8.0.0 to 8.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  > 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  > Manage apps > Bitbucket update check.

    2. Choose the version you plan to upgrade to then hit 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 Server.

      • 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.
   

Upgrade Bitbucket

This upgrade process does not perform an in-place upgrade, but instead installs the new version of Bitbucket Server into a new installation directory. The new instance uses your existing Bitbucket Server home directory and external database.

If necessary, rolling back an upgrade can only be performed by restoring a backup of both the Bitbucket Server home directory and the Bitbucket Server database – rolling back requires a consistent home directory and database. You can then reinstall the previous version of the application to the installation directory. Read the Rollback section for more details.

4. Download Bitbucket Server

Download the installer (the recommended approach) for your operating system - www.atlassian.com/software/bitbucket/download.

5. Back up your data

  1. Determine which backup strategy to use. 

    Summary of the different backup strategies for Bitbucket...

    For Bitbucket Server (version 4.8 or later) instances, you can use Zero Downtime Backup, the Backup Client (version 2.7 or later), or DIY Backup (version 2.12 or later) while Bitbucket is running, or just stop Bitbucket and zip up / snapshot the home directory and database and keep them somewhere safe.

    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.

 6. Migrate customizations

If upgrading from Bitbucket 4.x or earlier, see migrate customizations.


7. Stop the application

To stop Bitbucket Server from your Linux terminal, change to the <Bitbucket Server installation directory> and run:

bin/stop-bitbucket.sh
For Bitbucket Data Center...

Be sure to stop all nodes of Bitbucket Data Center, perform the steps to upgrade for a single node first, then repeat the process on each cluster node.

See the page Start and stop Bitbucket for more detailed instructions.

8. Run the installer

You can run the installer in GUI, console or unattended modes.

  1. Run the installer. 
    From your Linux terminal, change to the directory where you downloaded Bitbucket Server then execute this command to make the installer executable: 

    chmod +x atlassian-bitbucket-x.x.x-x64.bin

    We recommend using sudo to run the installer as this will create a dedicated account to run Bitbucket Server and allow you to run Bitbucket Server as a service.

    To use sudo to run the installer, execute this command: 

    $ sudo ./atlassian-bitbucket-x.x.x-x64.bin

    You can also run the installer with root user privileges.


  2. Follow the prompts to upgrade Bitbucket Server.

    1. At the 'Welcome' step, choose the type of instance to upgrade

      Help me decide which type of upgrade to choose...

      For a single node (most users), choose the Upgrade an existing Bitbucket instance option.

      For Bitbucket Data Center instances, choose the Upgrade an existing Bitbucket instance option, and repeat the upgrade process for each application node.

      For a Bitbucket mirror, choose the Upgrade an existing mirror option.

    2. At the 'Select Bitbucket Server Home' step, select your existing home directory.

    3. Proceed with the remaining installer steps.


9. Start the application

If you’re also upgrading your operating system libraries and using PostgresSQL and glibc version lower than 2.28, and the upgrade increases the glibc version to 2.28 or later, you’ll need to rebuild the PostgresSQL indices before starting Bitbucket.


When using the installer, there will be an option to start the application (and launch it in a browser) at the end of the installation wizard.


For a H2 database (on a Bitbucket Mirror or Server), you must
  1. Choose No at this option
  2. Change to your <Bitbucket Server installation directory>
  3. Migrate your H2 database to MvStore format. For detailed instructions, see Migrate H2 database.
  4. Start Bitbucket manually.

See the page Start and stop Bitbucket for more detailed instructions, including how to manually start Bitbucket.


Rollback

If necessary, rolling back an update can only be performed by restoring a backup of both the Bitbucket Server home directory and the Bitbucket Server database – rolling back requires a consistent home directory and database. You can then reinstall the previous version of the application to the installation directory. Never start an older binary against an upgraded home directory.

Check for known issues and troubleshooting

If something is not working correctly after you have completed the steps above to update your Stash installation, please check for known Stash issues and try troubleshooting your update as described below:

  • Check for known issues. Known issues can be seen in the BSERV project on our issue tracker.
  • Bitbucket Server Knowledge Base. Sometimes we find out about a problem with the latest version of Stash after we have released the software. In such cases we publish information in the Bitbucket Server Knowledge Base.
  • If you encounter a problem during the update and cannot solve it, please create a support ticket and one of our support engineers will help you.
Last modified on Jul 3, 2023

Was this helpful?

Yes
No
Provide feedback about this article

In this section

Related content

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