This page describes how to migrate an existing instance of Bitbucket Server to Bitbucket Data Center. For an overview, see Bitbucket Data Center resources. If you are installing Bitbucket Server instance go straight to Getting started instead. We also recommend reading Using Bitbucket Server in the enterprise.  If you just want to add another node we suggest you take a look at Adding cluster nodes to Bitbucket Data Center.

Overview and requirements

It's worth getting a clear understanding of what you're aiming to achieve, before starting to provision your Bitbucket Data Center.

A Bitbucket Data Center instance consists of a cluster of dedicated machines connected, and with  like this:

The URL of the Bitbucket Data Center instance will be the URL of the load balancer, so this is the machine that you will need to assign the name of your Bitbucket Server instance in the DNS. 

The remaining machines (Bitbucket cluster nodes, shared database, and shared file system) do not need to be publicly accessible to your users. 

1. Upgrade your existing production instance of Bitbucket Server

2. Back up your production instance

Now, take a backup of your production Bitbucket Server instance's database and home directory. For this you can:

• use the Bitbucket Server backup client,
• 独自の DIY バックアップ ソリューションを使用する、または
• Bitbucket Server を停止し、データベースを手動でダンプして、ホーム ディレクトリを zip ファイルに圧縮 

3. 共有データベースのプロビジョニング

Set up your shared database server. Note that clustered databases are not yet supported.

See Connecting Bitbucket Server to an external database for more information.

4. 共有ファイルシステムのプロビジョニング

Set up your shared file server.

NFS を使用する場合のパフォーマンス ガイドラインについては、「Bitbucket Data Center FAQ」を参照してください。

Create a Bitbucket Server user account (recommended name atlbitbucket) on the shared file system server to own everything in the Bitbucket Server shared home directory.  This user account must have the same UID on all cluster nodes and the shared file system server.  In a fresh Linux install the UID of a newly created account is typically 1001, but in general there is no guarantee that this UID will be free on every Linux system.  Choose a UID for atlbitbucket that's free on all your cluster nodes and the shared file system server, and substitute this for 1001 in the following command:

sudo useradd -c "Atlassian Bitbucket" -u 1001 atlbitbucket

Then restore the content of directory ${BITBUCKET_HOME}/shared from the backup you have taken in step 2 into the new shared database and shared home directory.

Only the shared directory in the Bitbucket Server home directory needs to be restored into the shared home directory. The remaining directories (bin, caches, export, lib, log, plugins, and tmp) contain only caches and temporary files, and do not need to be restored. 

5. Elasticsearch ノードのプロビジョニング

Elasticsearch is an engine that provides search functionality for Bitbucket Server.

To set up your Elasticsearch server, following the instructions on the page Install and configure a remote Elasticsearch instance.

6. Provision your cluster nodes

1. Chef、Puppet、または Vagrant などの自動構成管理ツールを使用するか、同一の仮想マシンのスナップショットをスピンアップすることで、クラスター ノードのプロビジョニングを行うことを強くお勧めします。 

2. On each cluster node, mount the shared home directory as ${BITBUCKET_HOME}/shared. For example, suppose your Bitbucket home directory is /var/atlassian/application-data/bitbucket , and your shared home directory is available as an NFS export called bitbucket-san:/bitbucket-shared . Add the following line to /etc/fstab on each cluster node:

   /etc/fstab

   bitbucket-san:/bitbucket-shared /var/atlassian/application-data/bitbucket/shared nfs lookupcache=pos,noatime,intr,rsize=32768,wsize=32768 0 0

   Only the ${BITBUCKET_HOME}/shared directory should be shared between cluster nodes. All other directories, including ${BITBUCKET_HOME}, should be node-local (that is, private to each node).

   Bitbucket Data Center checks during startup that ${BITBUCKET_HOME} is node local and ${BITBUCKET_HOME}/shared is shared, and will fail to form a cluster if this is not true.

   Your shared file system must provide sufficient consistency for Bitbucket Server and Git.

   Linux NFS clients require the lookupcache=pos mount option to be specified for proper consistency.

   これをマウントします。

   mkdir -p /var/atlassian/application-data/bitbucket/shared
   sudo mount -a

3. Ensure all your cluster nodes have synchronized clocks and identical timezone configuration. For example, in RedHat Enterprise Linux or CentOS:

   sudo yum install ntp
   sudo service ntpd start
   sudo tzselect

   In Ubuntu Linux:

   sudo apt-get install ntp
   sudo service ntp start
   sudo dpkg-reconfigure tzdata

   For other operating systems, consult your system documentation. 
   
   

   The system clocks on your cluster nodes must remain reasonably synchronized (say, to within a few seconds or less). If your system clocks drift excessively or undergo abrupt "jumps" of minutes or more, then cluster nodes may log warnings, become slow, or in extreme cases become unresponsive and require restarting. You should run the NTP service on all your cluster nodes with identical configuration, and never manually tamper with the system clock on a cluster node while Bitbucket Data Center is running.

4. Download the latest Bitbucket Data Center distribution from https://www.atlassian.com/software/bitbucket/download, and install Bitbucket Server as normal on all the cluster nodes. See Install Bitbucket Server on Linux from an archive file or Install Bitbucket Server on Windows from a zip file for installation instructions.

7. 最初のクラスタ ノードの起動

Edit the file ${BITBUCKET_HOME}/shared/bitbucket.properties , and add the following lines:

# Use multicast to discover cluster nodes (recommended).
hazelcast.network.multicast=true

# If your network does not support multicast, you may uncomment the following lines and substitute
# the IP addresses of some or all of your cluster nodes. (Not all of the cluster nodes have to be
# listed here but at least one of them has to be active when a new node joins.) 
#hazelcast.network.tcpip=true
#hazelcast.network.tcpip.members=192.168.0.1:5701,192.168.0.2:5701,192.168.0.3:5701

# The following should uniquely identify your cluster on the LAN. 
hazelcast.group.name=your-bitbucket-cluster
hazelcast.group.password=your-bitbucket-cluster

Using multicast to discover cluster nodes (hazelcast.network.multicast=true) is recommended, but requires all your cluster nodes to be accessible to each other via a multicast-enabled network. If your network does not support multicast then you can set  hazelcast.network.multicast=false,  hazelcast.network.tcpip=true, and hazelcast.network.tcpip.members to a comma-separated list of cluster nodes instead. Only enable one of hazelcast.network.tcpip or hazelcast.network.multicast, not both.

Choose a name for hazelcast.group.name and hazelcast.group.password that uniquely identifies the cluster on your LAN. If you have more than one cluster on the same LAN (for example, other Bitbucket Data Center instances or other products based on similar technology such as Confluence Data Center) then you must assign each cluster a distinct name, to prevent them from attempting to join together into a "super cluster". 

Bitbucket Server を起動します。「Bitbucket Server の開始および終了」をご参照ください。

Then go to http://<bitbucket>:7990/admin/license, and install your Bitbucket Data Center license. Restart Bitbucket Server for the change to take effect. If you need a Bitbucket Data Center license, you can purchase one that fits your needs, or, get an evaluation license.

8. Install and configure your load balancer 

ハードウェアでもソフトウェアでもお好みのロード バランサを使用できます。Bitbucket Data Center にはロード バランサがバンドルされません。 

ロード バランサは 3 つのプロトコルをプロキシする必要があります。

If your load balancer supports health checks of the cluster nodes, configure it to perform a periodic HTTP GET of http:// <bitbucket>:7990/status, where <bitbucket> is the cluster node's name or IP address. This returns one of two HTTP status codes:

• 200 OK
• 500 Internal Server Error

クラスタ ノードが合理的な時間内に 200 OK を返さない場合、ロード バランサはそのクラスタ ノードにトラフィックを転送するべきではありません。 

You should then be able to navigate to http://<load-balancer>/, where <load-balancer> is your load balancer's name or IP address. This should take you to your Bitbucket Server front page. 

例: HAProxy ロード バランサ

使用するロード バランサが決まっていなかったり、ロード バランサに対するポリシーがなかったりする場合、人気のオープン ソースおソフトウェア ロード バランサである HAProxy を使用できます。

Here is an example haproxy.cfg configuration file (typically found in the location /etc/haproxy/haproxy.cfg).  This assumes:

• Bitbucket クラスタ ノードのアドレスは 192.168.0.1 であり、デフォルト ポート 7990 (HTTP) および 7999 (SSH) でリッスンしている。 
• You have a valid SSL certificate at /etc/cert.pem.

global
    pidfile     /var/run/haproxy.pid
    maxconn     4000
    user        haproxy
    group       haproxy
    daemon
    tune.ssl.default-dh-param 1024
defaults
    log                     global
    option                  dontlognull
    option                  redispatch
    retries                 3
    timeout http-request    10s
    timeout queue           1m
    timeout connect         10s
    timeout client          1m
    timeout server          1m
    timeout http-keep-alive 10s
    timeout check           10s
    maxconn                 3000
    errorfile               408 /dev/null	# Workaround for Chrome 35-36 bug.  See http://blog.haproxy.com/2014/05/26/haproxy-and-http-errors-408-in-chrome/

frontend bitbucket_http_frontend
    bind *:80
    bind *:443 ssl crt /etc/cert.pem ciphers RC4-SHA:AES128-SHA:AES256-SHA
    default_backend bitbucket_http_backend

backend bitbucket_http_backend
    mode http
    option httplog
    option httpchk GET /status
    option forwardfor
    option http-server-close
    appsession BITBUCKETSESSIONID len 52 timeout 1h
    balance roundrobin
    cookie BITBUCKETSESSIONID prefix
    stick-table type string len 52 size 5M expire 30m
    stick store-response set-cookie(BITBUCKETSESSIONID)
    stick on cookie(BITBUCKETSESSIONID)
    server bitbucket01 192.168.0.1:7990 check inter 10000 rise 2 fall 5
    #server bitbucket02 192.168.0.2:7990 check inter 10000 rise 2 fall 5
    # The following "backup" servers are just here to show the startup page when all nodes are starting up
    server backup01 192.168.0.1:7990 backup
    #server backup02 192.168.0.2:7990 backup

frontend bitbucket_ssh_frontend
    bind *:7999
    default_backend bitbucket_ssh_backend
    timeout client 15m
    maxconn 50

backend bitbucket_ssh_backend
    mode tcp
    balance roundrobin
    server bitbucket01 192.168.0.1:7999 check port 7999
    #server bitbucket02 192.168.0.2:7999 check port 7999
    timeout server 15m

listen admin
    mode http
    bind *:8090
    stats enable
    stats uri /

Once you have configured the haproxy.cfg file, start the haproxy service.

sudo service haproxy start

You can also monitor the health of your cluster by navigating to HAProxy's statistics page at http://<load-balancer>:8090/. You should see a page similar to this:

9. Configure Tomcat/Bitbucket for HAProxy

Bitbucket を、HAProxy と連携するように設定する必要があります。例:

server.proxy-name=bitbucket.company.com
server.proxy-port=443
server.secure=true
server.require-ssl=true

Securing Bitbucket behind HAProxy using SSL for more details.

10. Add a new Bitbucket cluster node to the cluster

新しいクラスタ ノードに移動し、Bitbucket Server を起動します。「Bitbucket Server の開始および終了」をご参照ください。

Once Bitbucket Server has started, go to https://<load-balancer>/admin/clustering. You should see a page similar to this:

Verify that the new node you have started up has successfully joined the cluster. If it does not, please check your network configuration and the ${BITBUCKET_HOME}/log/atlassian-bitbucket.log files on all nodes. If you are unable to find a reason for the node failing to join successfully, please contact Atlassian Support .

11. 新しい Bitbucket クラスタ ノードをロード バランサに接続

独自のハードウェアまたはソフトウェア ロード バランサを使用している場合、新しい Bitbucket クラスタ ノードをロード バランサに追加する方法については、ベンダーのドキュメントを参照してください。

HAProxy を使用している場合、次の行のコメント化を解除します。

server bitbucket02 192.168.0.2:7990 check inter 10000 rise 2 fall 5

server bitbucket02 192.168.0.2:7999 check port 7999

in your haproxy.cfg file and restart haproxy:

sudo service haproxy restart

新しいノードがクラスター内にあり、リクエストを受信することを検証します。これを行うには、各ノードでログを調べ、いずれもトラフィックを受信していることを確認し、さらに、一方のノードで実行された更新をもう一方のノードで表示できるかどうかも調べます。 

12. Repeat steps 10 and 11 for each additional cluster node

おめでとうございます!

You have now set up a clustered instance of Bitbucket Data Center!  We are very interested in hearing your feedback on this process – please contact us!

Please see Using Bitbucket Server in the enterprise for information about using Bitbucket Server in a production environment.