Moving Atlassian Bitbucket Server to a new computer
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.
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:
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.
Thanks for detail migration steps. I’m planning to migrate Bitbucket server to new server by using same SQL database.
Below are the steps
– Install latest Bitbucket version on new server.
– Create the new database on different database server and make the changes to bitbucket.properties. This is to test the application before go live
– Stop the Bitbucket server on new server
– Take SQL backup from old database and restore it to new database
– Copy the Home directory from old server to new server
– Start the Bitbucket server instance
– Test the Projects and Repositories on new server.
Before we go live on new server, I’m planning to just update the old database name and server details on bitbucket.properties and then sync the final home directory to new directory. Do you see any issue with this approach?. or Do we just the restore final DB backup from old server to new server?
Also is there any way to migrate only some project repositories so that we can test it before we sync the home directory?
You mean the new database, right?
Do you see any issue with this approach?. or Do we just the restore final DB backup from old server to new server?
I think it will work. What system are you on? Maybe you need to change the folder permissions on Linux distributions
Perhaps if you copy only the repos you want. But then, you need to copy any secondary folders to make it work and this can become complicated. I think the safe bet here is to copy the whole Home Directory. If you have huge projects/repos I understand why you are considering this
Thanks John for your reply. Currently We are on Windows 2008 R2 server and I’m planning to install on Windows 2016 with latest Bitbucket version.
Once I test the bitbucket application on new server by using new database, then during go-live I would like to perform below steps. Do you see any issue with this approach?.
– Stop the bitbucket on old server
– Stop the bitbucket on new server
– update the bitbbucket.properties on new server to use old database name and old database server
– Sync the home directory between old bitbucket server and new bitbucket server
– Start the bitbucket on new server
– Test the bitbucket on new server
the sequence of events as you describe them make sense and I am pretty sure you will not get any conflicts. As long as the two servers do not use the same repo at the same time I think you can safely migrate your data as you describe
I recently wrote a piece on the importance of restores where I give practical example on how to use Docker to spin up an Atlassian BitBucket and a MySQL container and import your existing backup. It may come in handy to check your backups (the ideia) and may also help some readers who are here trying to migrate to a new computer. By spinning up a container you’ll get instant feedback on the issues ahead.
thanks for sharing.
Looks interesting indeed.
Thanks for this fantastic tutorial, I had been trying to recover a bitbucket server installation for hours without success.
Yeah, it’s still a pain.