I run my own instance of Atlassian Bitbucket Server and I, recently, had to move Bitbucket to a new computer. Actually, I moved from a macOS based machine to a Windows 10 computer.

Unfortunately, Bitbucket Server does not provide an option to Backup and Restore the database from the administration panel, something you can find in both JIRA and Confluence. There is an official guide about how to migrate Bitbucket Server to another server and how to use the Backup Client but what you end up with is your previous installation with all the redundant git hooks, orphan folders and repos (I know, I know; this should never happen but here we are…).

What I want to have is a clean Bitbucket installation and, still, have all my repositories, branches, and, even, my avatar in place. What follows is an alternative guide.

Preparation

The first thing we need is the database itself. Here I assume you are using an external database compatible with Atlassian’s requirements. In the old system, connect to the database and dump the full database (both the structure and the content) in a .sql file. There are many ways to do this. I, personally, use software like Navicat or SQLite Manager, depending on the type of database in place.

Then, what we, also, need is the <Bitbucket Home Directory>\shared\data folder and all its subfolders. We will come to this in a while.

Installation of Bitbucket Server

Create a new database and install the Server as described in the official documentation. Create a new home directory and use a new (empty) database following the guidelines about Bitbucket not being installed at all with a database or a folder with, already, populated data. Create a user account, complete the configuration and have the server up and running. Once you confirm that the server is working as expected we can move to the next step.

Importing the Database

The first thing that comes to mind is to use the .sql file we generated earlier and import the data into the database we used for the installation of the server. This would require us to delete the tables Bitbucket Server has, already, created. Well, this proves to be a not so easy job as there are dependencies and foreign keys and it would require us to know the correct order of deletion. All in all, this is a laborious task.

The alternative is to generate a new database using the step-by-step guides as found in the official documentation. First stop the Bitbucket Server. Then, use the tool of your preference and import the .sql file into the newly created database.

We, now, need to tell Bitbucket to use this new database. Although you can see the connection details in the administration panel while the server is running, you are not able to change it. We, therefore, need to do this manually. Stop the server, go to <Bitbucket Home Directory>\shared\ folder and open the bitbucket.properties file. This is the file where the server get the information about the database inuse. Change the name of the database to reflect your new database. I use PostgreSQL, so my file has the following line:

jdbc.url=jdbc:postgresql://localhost:5432/newBitbucketDatabase

I have, only, changed the name of the database (newBitbucketDatabase). Note that although I used Caps, this is not relevant as BitBucket ignores cases. Now, you can restart the server.

Importing the Repositories

After the change of the database, if you login to Bitbucket, you will be able to see your projects…followed by a surprise. The projects are all there but not the repositories. This is because repository data is kept outside the database. Thankfully, this is not that hard to resolve. As previously, stop the server first. Then, you need to copy the <Bitbucket Home Directory>\shared\data folder from the old location to the new home directory.

Starting up the server again will, hopefully, allow you to see all your repositories, attachments, and avatars where you expect them to be.

Suggestions, Improvements, Omissions, Mistakes

If you have suggestions and ideas how to improve this article or have spotted an error, please leave a comment or contact me. Thanks.