Migrate Bitbucket Server from Windows to Linux
Bitbucket 8.14.x is the last version that’ll support Server licenses. Learn what this means for you
This page describes how to migrate your Bitbucket Server instance from Windows to Linux operating system. For most scenarios, the overall procedure involves the following 4 steps:
You can upgrade Bitbucket Server after migrating to Linux. See Bitbucket Server upgrade guide for more details. This page does not describe any aspect of the upgrade procedure.
We recommend testing the migration on your staging/test instance before performing it on production. You can refer How to establish staging server environments for Bitbucket Server to set up your staging instance.
On this page
Related pages:
Prepare for migration
Set up your Linux server.
Starting Bitbucket Server 7.0+, Linux support requires a 2.6.17+ kernel and glibc 2.7+. That means RHEL 5, which uses glibc 2.5, is no longer supported for Bitbucket Sever 7.0+.
Confirm that the operating system, database, other applicable platforms, and hardware on the target environment will comply with the requirements for Bitbucket Server.
Plan to migrate to a target server that runs the same version of Bitbucket as the source server.
Make sure you have created a user in Bitbucket Server (not in your external user directory) that has System Administrator global permissions. This is to avoid being locked out of Bitbucket Server in case the target server does not have access to your external user directory.
Alert users to the forthcoming Bitbucket Server service outage.
Ensure that users will not be able to update existing Bitbucket Server data during the migration. You can do this by temporarily changing the access permissions for Bitbucket Server or entering into maintenance mode while taking backup using Bitbucket backup strategies.
- Perform a full backup of Bitbucket home directory and database using one of the backup strategies.
(Optional) Move Bitbucket Server database
This section describes steps to move your database to a different server or different supported database. You can use the existing database or move to a different database for Bitbucket Server on Linux. You do not need to do anything in this section if you are going to continue using the existing database as Windows. Please make sure to shut down Bitbucket Server running on your Windows instance.
If you plan to move your database, you can move the Bitbucket Server data:
from the embedded database to a supported external database.
to another instance of the same database.
from one database to another supported database (for example, from MySQL to PostgreSQL).
You can also move the actual DBMS. Atlassian recommends that for large installations, Bitbucket Server and the DBMS run on separate machines.
There are 2 steps:
Create and configure the database in the new location. Please refer to Connect Bitbucket to an external database, and the relevant child page, for more information.
Either:
If the new location is currently visible to Bitbucket Server, use the Database Migration Wizard. Please refer to Connect Bitbucket to an external database, and the relevant child page, for more information.
If the new location is not currently visible to Bitbucket Server (perhaps because you are moving to a new hosting provider), you need to perform a database export and then import the backup to the new DBMS. Please refer to the vendor documentation for detailed information on your DBMS.
You will also need to update the bitbucket.properties file in the<Bitbucket home directory>as described in the section below.
Please note that Using Windows Authentication between a Linux Bitbucket Server installation and SQL server is not supported. Windows authentication is only available for Bitbucket instances running on Windows. It cannot be used on Linux because Microsoft does not provide shared objects for it. You will need to enable mixed-mode authentication for SQL Server if you are running Bitbucket on Linux.
Data backup and migration of Bitbucket Server data from Windows to Linux machine
This section gives a brief overview of how to backup and move the Bitbucket Server data to your Linux machine.
On Windows Server:
Perform a full backup of the Bitbucket Server instance that includes Bitbucket home directory and database. The home directory contains data directories (including the Git repositories), log files, installed plugins, SSH fingerprints, temporary files, and caches. The database contains Bitbucket specific data such as pull requests, comments, user permissions, etc.
To archive
BITBUCKET_HOMEdirectory manually, refer to Migrate Bitbucket Server to a different machine.Make sure that the home directory and database are backed up at the same time to avoid sync issues.
We recommend creating a backup using one of the available backup strategies. This ensures consistency between filesystem and database data.
4. Shutdown Bitbucket Server. See Start and stop Bitbucket.
5. Move the backup to your Linux Server.
On target Linux Server:
Make sure you have installed the dependencies such as JDK/JRE, and Git on your Linux Server.
Restore
BITBUCKET_HOMEdirectory data from the backup onto the newBITBUCKET_HOMEdirectory.Download the same version of Bitbucket as your Windows instance from archives.
Install Bitbucket Server from scratch using the Bitbucket installation guide for Linux.
If you install Bitbucket Server from an archive file:
Update the newBITBUCKET_HOMEdirectory path inset-bitbucket-home.shlocated in installation directory at$BITBUCKET_INSTALL/bin$ vi $BITBUCKET_INSTALL/bin/set-bitbucket-home.sh # One way to set the BITBUCKET_HOME path is here via this variable. Simply uncomment it and set a valid path like # /bitbucket/home. You can of course set it outside in the command terminal; that will also work. # if [ -z "$BITBUCKET_HOME" ]; then BITBUCKET_HOME="<YOUR_NEW_BITBUCKET_HOME where data is restored from Windows>" fiMake sure the user with which Bitbucket runs has full (read/write/execute) permissions on
BITBUCKET_HOMEandBITBUCKET_INSTALLdirectories.atlbitbucketuser is created by default during installation.If you install Bitbucket Server through Linux installer:
Specify the new BITBUCKET_HOME directory path during installation.$sudo ./atlassian-bitbucket-X.X.X-x64.bin Starting Installer ... . . The location for Bitbucket data. This will be the default location for repositories, plugins, and other data. Ensure that this location is not used by another Bitbucket installation. [/var/atlassian/application-data/bitbucket] <YOUR_NEW_BITBUCKET_HOME where data is restored from Windows>Make sure the user with which Bitbucket runs has full (read/write/execute) permissions on
BITBUCKET_HOMEandBITBUCKET_INSTALLdirectories. Theatlbitbucketuser is created by default during installation.
5. If you moved Bitbucket Server database data by performing a database export, you must update the bitbucket.properties file within <BITBUCKET_HOME>/shared with the changed configuration parameters for the database connection.
jdbc.driver=<Database driver>
jdbc.url=<JDBC URL that will be used to connect to the database>
jdbc.user=<the JDBC user that will be used to authenticate with the database>
jdbc.password=<JDBC user password>The configuration parameters are described in Configuration properties.
You do not need to do anything if you are going to continue using the existing database as Windows.
6. Start Bitbucket Server on Linux. See Start and stop Bitbucket.
7. Once you have confirmed that the new installation of Bitbucket Server is working correctly, revert users' access permissions for Bitbucket Server (if you temporarily changed them at the time of migration).
Troubleshooting
If something is not working correctly after you have completed the steps above to migrate your Bitbucket instance, please check for known issues and try troubleshooting as described below:
If
$BITBUCKET_HOMEwas using a symbolic link in the original instance, you may encounter some issues with forked repositories in the new instance. Check the details in the knowledge base article to resolve error object directory does not exist.If you encounter a problem during migration and cannot solve it, please create a support ticket and one of our support engineers will help you.