How to migrate to Docker and upgrade Bitbucket Server

Still need help?

The Atlassian Community is here for you.

Ask the community

Platform Notice: Server and Data Center Only - This article only applies to Atlassian products on the server and data center platforms.


This page describes how to migrate from Bitbucket on-prem to dockerized Bitbucket and upgrade Bitbucket version.


  • You'll need to run the container defining the current <Bitbucket-home> directory during the docker startup as a parameter or in a Dockerfile.
  • Don't forget to mount <Bitbucket-home> directory. Basically, that's a single migration step, in case you keep using the same database.
  • You can keep using Bitbucket properties file if that's more convenient for you, but surely environment variables make more sense for dockerized app. Say, if the property name was the env var name will be FOO_BAR. Follow the same pattern for all properties and create an env file if necessary.

This is what the steps would be:

  1. Create docker volume (optional, in case you want to keep Bitbucket home in a pre-defined host location)

    docker volume create --name bitbucketVolume
  2. Copy existing <Bitbucket-home> to a docker volume directory. This is just a sample command, please use the correct command according to the environment Bitbucket is currently in. If you mount to a pre-defined host path, move <Bitbucket-home> there. This step is optional if you want to mount an existing Bitbucket home on the same server when docker runs.

    cp -r /old/bb-home/* /var/lib/docker/volumes/bitbucketVolume/_data
  3. Run Bitbucket

    docker run -v bitbucketVolume:/var/atlassian/application-data/bitbucket --name="bitbucket" -d -p 7990:7990 -p 7999:7999 atlassian/bitbucket-server

    You may need to chmod /var/lib/docker/... in case there are any permission issues.

    Alternatively, you may run with a host binding as follows (in case you pre-created a new host directory and moved existing Bitbucket home in there, or used an existing Bitbucket home directory to mount into the container):

     -v /existing/home:/var/atlassian/application-data/bitbucket
  • You'll need to be on the lookout for any permission issues and fix them accordingly.
  • The file is in <Bitbucket-home>/shared directory so Bitbucket will read it. It may be better (more convenient) to create an environment file and pass it in docker run syntax to use environment variables instead of a file. See: DockerHub page.
  • When changing <Bitbucket-home> inside the container, you'll need to change the volume mount binding too.
  • As for the database, if you keep using the same database, nothing changes then, as long as it's available from within the container. If you want to dockerize the database, you may then want to use Docker Compose and connect to database by service name, or run containers separately but join one docker network or expose and publish Database port making it accessible from outside.

 Once you've migrated to docker environment, please follow the steps given in the Upgrade section of atlassian/bitbucket-server to upgrade your Bitbucket version.

Last modified on Mar 30, 2021

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.