Bitbucket Server upgrade guide
Starting from 8.15.x, new releases of Bitbucket will be available only to Data Center customers. If you have a Server license, learn about your options.
Use this document only if you're upgrading to Bitbucket Server 8.14 or earlier.
If you want to upgrade to Bitbucket 8.15 or later, go to Bitbucket Data Center upgrade guide.
If you try to upgrade to release 8.15 or later with your Server license, Bitbucket will fail to start, and you’ll need to downgrade. To do this, follow our Bitbucket Server downgrade guide.
If you’re using bundled search, you’ll also need to delete search index data before downgrading Bitbucket.
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:
- Manually – upgrade using an archive file.
- Data Center – upgrade your Data Center cluster
- Rolling upgrade - upgrade your Data Center cluster to the next bug fix update, without downtime
- Docker container image for Bitbucket Server.
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? | |
Are you eligible to upgrade? | |
Have our support platforms changed? | |
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. |
Are you upgrading from Bitbucket 4.x or earlier and have you modified your server.xml file? |
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’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 8.x is a major upgrade
Be sure to read the Bitbucket 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.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 and Server 8.x before upgrading.
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
- 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.
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
Take this step only if you're upgrading to Bitbucket Server 8.14 or earlier.
Download the installer (the recommended approach) for your operating system - www.atlassian.com/software/bitbucket/download.
5. Back up your data
Determine which backup strategy to use.
- 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
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.
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.
- Follow the prompts to upgrade Bitbucket Server.
At the 'Welcome' step, choose the type of instance to upgrade
At the 'Select Bitbucket Server Home' step, select your existing home directory.
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.
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 Bitbucket installation, please check for known 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 Knowledge Base. Sometimes we find out about a problem with the latest Bitbucket version after we have released the software. In such cases we publish information in the Bitbucket 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.