The key to reducing downtime is the use of optimal, vendor-specific database and file system backup tools. Bitbucket DIY Backup does require you to write some code in a language of your choice to perform the required backup steps, using the REST API available for Bitbucket Server and Data Center 4.0.

DIY Backup supports Windows and Linux platforms, and Bitbucket version 4.0 and higher. DIY Backup supports Bitbucket Data Center and Bitbucket Mesh instances equally – any DIY Backup solution that works on one should work on the other without modification.

For information about other backup strategies for Bitbucket Data Center, see Data recovery and backups. That page also discusses the tight coupling between the Bitbucket Data Center file system on disk and the database that the application uses.

このページでは次のような内容について説明します。

• bash シェル スクリプトを使用した、PostgreSQL データベースおよびローカル ファイルシステム用の完全な DIY Backup ソリューションについて説明します。
• Provides background information about how the Bitbucket Data Center REST API can be used for DIY Backups.

You can use this solution directly if your Bitbucket Data Center instance has the same or similar configuration, or use this as a starting point to develop your own DIY Backup solution tailored to your hardware configuration. 

動作の仕組み

When you use DIY Backup, you have complete control over the backup steps, and can implement any custom processes you like in the language of your choice. For example, you can use your database's incremental or fast snapshot tools and/or your file server's specific tools as part of a DIY Backup. 

The DIY Backup does the following:

1. Prepares the Bitbucket Data Center instance for backup. This happens before Bitbucket Data Center is locked, so we want to do as much processing as possible here in order to minimize downtime later. For example, we can take an initial snapshot using incremental database and filesystem utilities. These do not have to be 100% consistent as Bitbucket Data Center is still running and modifying the database and filesystem. But taking the initial snapshot now may reduce the amount of work done later (while the application is locked), especially if the amount of data modified between backups is large. The steps include:
   • データベースの最初のバックアップを実行する (プログレッシブ/差分バックアップをサポートしている場合)。
   • ホーム フォルダからバックアップ フォルダへの初回の rsync を実行する。
2. バックアップを初期化します。これにより、以下が行われます。
   • Lock the Bitbucket Data Center instance.
   • データベースおよびファイルシステムへのコネクションがドレインおよびラッチされる。
   • ドレイン/ラッチ手順の完了を待機する。
3. インスタンスでバックアップの準備が整ったら、実際の DIY Backup を開始できます。これには、次の手順が含まれます。
   • pg_dump を使用して、データベースの完全に一貫したバックアップを作成する。

   • rsync を使用して、ファイルシステムの完全に一貫したバックアップを作成する。

     リポジトリの保存に Bitbucket Mesh を使用している場合は、この段階で各リポジトリで DIY Backup スクリプトを実行する必要があります。

4. Notify the Bitbucket Data Center instance once the backup process finishes and unlock it.
5. バックアップ中に作成したすべてのファイルを 1 つの大きなアーカイブに保存します。

アプリケーションがメンテナンス モードになっている場合、ユーザーが Web インターフェイスへのアクセスやホスティング サービスの使用を試みると、エラー メッセージが表示されます。

As an indication of the unavailability time that can be expected, in Atlassian's internal use we have seen downtimes of less than a minute.

バックアップ対象

The Bitbucket DIY Backup backs up the following data:

• the database the instance is connected to (either the internal or external database)
• 管理された Git リポジトリ
• the Bitbucket Data Center logs
• インストール済みのプラグインとそれらのデータ

Bash スクリプトを使用した DIY Backup

このセクションでは、次のツールを使用する、完全な DIY Backup ソリューションを紹介します。

• bash -スクリプト用
• jq - an open source command line JSON processor for parsing the REST responses from Bitbucket Data Center
• pg_dump (または sqlcmd) - PostgreSQL データベースのバックアップ用
• rsync - ファイルシステムのバックアップ用
• tar - バックアップ アーカイブの作成用

このアプローチに小規模な変更を加えることで、以下で DIY Backups を実行するために使用できます。

• Linux と Unix
• macOS
• Windows with cygwin.

Bash スクリプト

Bitbucket からサンプル スクリプトをダウンロードするか、リポジトリをクローンできます。

Bash スクリプトの実行

Bash スクリプトをダウンロードしたら、1 つのファイルを作成する必要があります。

• bitbucket.diy-backup.vars.sh ( bitbucket.diy-backup.vars.sh.example をコピーして開始できます)

たとえば、次の場合の bitbucket.diy-backup.vars.sh の設定方法を紹介します。

• your Bitbucket Data Center server is called bitbucket.example.com, uses port 7990, and has its home directory in /bitbucket-home
• /bitbucket-backup にバックアップを生成し、.tar.gz バックアップを /bitbucket-backup-archives に保存したい
• Bitbucket にユーザー名 "admin"、パスワード "admin" のシステム管理者があり、OS ユーザー "atlbitbucket" として Bitbucket (およびバックアップ スクリプト) を実行する。

提供の  bitbucket.diy-backup.vars.sh は、デフォルトで PostgreSQL、rsync、tar を使用するように書かれています。別のツールを使用したい場合、このファイルの上部のセクションをカスタマイズすることもできます。

DIY Backup が機能するには、2 つのディレクトリを作成する必要があります。

1. ${BITBUCKET_BACKUP_ROOT} is a working directory (/bitbucket-backup in our example) where copies of Bitbucket Data Center home directory and database dump are built during the DIY Backup process. 
2. ${BITBUCKET_BACKUP_ARCHIVE_ROOT} is the directory (/bitbucket-backup-archives in our example) where the final backup archives are saved. 

Bash スクリプトが以下の条件を満たしている場合、このスクリプトをあらゆるホストで実行できます。

• 上記の ${BITBUCKET_BACKUP_ROOT} および ${BITBUCKET_BACKUP_ARCHIVE_ROOT} ディレクトリへの読み取り/書き込みアクセス、
• ${BITBUCKET_HOME} ディレクトリへの読み取りアクセス、
• データベースへの読み取りアクセス
• network access to run curl commands on the Bitbucket Data Center server. 

It doesn't matter whether the filesystem access is direct or over NFS, or whether the network access is direct to a node or to a load balancer / reverse proxy. 

bitbucket.diy-backup.vars.sh が正しく設定できたら、ターミナル ウィンドウでバックアップを実行してください。

$ ./bitbucket.diy-backup.sh 

The first time you run the backup, rsync will do most of the work since the /bitbucket-backup working directory is initially empty. This is normal. Fortunately, this script performs one rsync before locking Bitbucket Data Center, followed by a second rsync while Bitbucket Data Center is locked to minimize downtime. 

On second and subsequent backup runs,  /bitbucket-backup is already populated so the backup process should be faster. The output you can expect to see looks something like this:

$ ./bitbucket.diy-backup.sh
[http://localhost:7990/bitbucket]  INFO: Prepared backup of DB bitbucket in /bitbucket-backup/bitbucket-db/
building file list ... done.
sent 4.17M bytes  received 484 bytes  2.78M bytes/sec
total size is 121.12M  speedup is 29.06
[http://localhost:7990/bitbucket]  INFO: Prepared backup of /bitbucket-home to /bitbucket-backup/bitbucket-home/
[http://localhost:7990/bitbucket]  INFO: locked with '7187ae1824ce1ede38a8e7de4bccf58d9a8e1a7a'
[http://localhost:7990/bitbucket]  INFO: backup started with '82c73f89e790b27fef3032e81c7071388ae4e371'
[http://localhost:7990/bitbucket]  INFO: Waiting for DRAINED state....... done
[http://localhost:7990/bitbucket]  INFO: db state 'DRAINED'
[http://localhost:7990/bitbucket]  INFO: scm state 'DRAINED'
[http://localhost:7990/bitbucket]  INFO: Performed backup of DB bitbucket in /bitbucket-backup/bitbucket-db/
[http://localhost:7990/bitbucket]  INFO: Backup progress updated to 50
building file list ... done.
sent 4.87M bytes  received 484 bytes  3.25M bytes/sec
total size is 121.82M  speedup is 24.99
[http://localhost:7990/bitbucket]  INFO: Performed backup of /bitbucket-home to /bitbucket-backup/bitbucket-home/
[http://localhost:7990/bitbucket]  INFO: Backup progress updated to 100
[http://localhost:7990/bitbucket]  INFO: Bitbucket instance unlocked
[http://localhost:7990/bitbucket]  INFO: Archiving /bitbucket-backup into /bitbucket-backup-archives/bitbucket-20150917-082818-498.tar.gz
[http://localhost:7990/bitbucket]  INFO: Archived  /bitbucket-backup into /bitbucket-backup-archives/bitbucket-20150917-082818-498.tar.gz

DIY Backup の復元

When restoring Bitbucket Data Center, you must run the bitbucket.diy-restore.sh script on the machine that Bitbucket Data Center should be restored to. In order to ensure accidental restores do not delete existing data, you should never restore into an existing home directory.

新しいデータベースは、「Bitbucket を外部データベースに接続する」およびご利用のデータベース タイプに対応するサブページの指示にしたがって構成されている必要があります。 

${BITBUCKET_BACKUP_ARCHIVE_ROOT} ディレクトリにある利用可能なバックアップを確認するには、次のように入力してください。

$ ./bitbucket.diy-restore.sh

次のように表示されるはずです。

$ ./bitbucket.diy-restore.sh
Usage: ./bitbucket.diy-restore.sh <backup-file-name>.tar.gz
Available backups:
bitbucket-20150917-082818-498.tar.gz  bitbucket-20150918-083745-001.tar.gz

To restore a backup, run bitbucket.diy-restore.sh with the file name as the argument:

$ ./bitbucket.diy-restore.sh bitbucket-20150917-082818-498

出力は次のように表示されます。

$ ./bitbucket.diy-restore.sh bitbucket-20150917-082818-498.tar.gz
[http://localhost:7990/bitbucket]  INFO: Extracted /bitbucket-backup-archives/bitbucket-20150917-082818-498.tar.gz into /tmp/bitbucket.diy-restore.dQsbzU
[http://localhost:7990/bitbucket]  INFO: Performed restore of /tmp/bitbucket.diy-restore.dQsbzU/bitbucket-db to DB bitbucket2
[http://localhost:7990/bitbucket]  INFO: Performed restore of /tmp/bitbucket.diy-restore.dQsbzU/bitbucket-home to /bitbucket-home2

バックアップのキャンセル

必要に応じて、実行中のバックアップ操作をキャンセルできます。

バックアップのキャンセル方法

1. ターミナル (または Windows のコマンド プロンプト) で返されるキャンセル トークンをコピーします。「backup started with token」行を探します。

   $ ./bitbucket.diy-backup.sh
   [http://localhost:7990/bitbucket]  INFO: Prepared backup of DB bitbucket in /bitbucket-backup/bitbucket-db/
   building file list ... done.
   sent 4.17M bytes  received 484 bytes  2.78M bytes/sec
   total size is 121.12M  speedup is 29.06
   [http://localhost:7990/bitbucket]  INFO: Prepared backup of /bitbucket-home to /bitbucket-backup/bitbucket-home/
   [http://localhost:7990/bitbucket]  INFO: locked with '7187ae1824ce1ede38a8e7de4bccf58d9a8e1a7a'
   [http://localhost:7990/bitbucket]  INFO: backup started with '82c73f89e790b27fef3032e81c7071388ae4e371'
   [http://localhost:7990/bitbucket]  INFO: Waiting for DRAINED state....... done
   [http://localhost:7990/bitbucket]  INFO: db state 'DRAINED'
   [http://localhost:7990/bitbucket]  INFO: scm state 'DRAINED'

   例: "82c73f89e790b27fef3032e81c7071388ae4e371" を使用

2. Go to the Bitbucket Data Center interface in your browser. Bitbucket Data Center will display this screen:
   
   
3. [バックアップを取消] をクリックし、キャンセル トークンを入力します。
   
   
4. [バックアップを取消] をクリックします。

Note that Bitbucket Data Center will still be locked in maintenance mode. Repeat these steps using the "locked with" token (e.g. "7187ae1824ce1ede38a8e7de4bccf58d9a8e1a7a") to exit maintenance mode as well, and unlock Bitbucket Data Center.

Advanced – writing your own DIY Backup using the REST APIs

ここでは、Bash での curl コマンドを示していますが、任意の言語を使用できます。

次の手順が含まれます。

準備

Before you lock Bitbucket Data Center, you can perform any preparation you like. It makes sense to perform as much processing as possible before you lock the application, to minimize downtime later. For example, you could perform an rsync:

rsync -avh --delete --delete-excluded --exclude=/caches/ --exclude=/data/db.* --exclude=/export/ --exclude=/log/ --exclude=/plugins/.*/ --exclude=/tmp --exclude=/.lock ${BITBUCKET_HOME} ${BITBUCKET_BACKUP_HOME}

Lock the Bitbucket Data Center instance

The next step in making a backup of a Bitbucket Data Center instance is to lock the instance for maintenance. This can be done using a POST request to the /mvc/maintenance/lock REST point (where BITBUCKET_URL points to the Bitbucket Data Center instance, BITBUCKET_BACKUP_USER is a Bitbucket Data Center user with backup permissions, and BITBUCKET_BACKUP_PASS is this user's password).

curl -s \
	 -u ${BITBUCKET_BACKUP_USER}:${BITBUCKET_BACKUP_PASS} \
	 -X POST \
	 -H "Content-type: application/json" \
     "${BITBUCKET_URL}/mvc/maintenance/lock"

{
	"unlockToken":"0476adeb6cde3a41aa0cc19fb394779191f5d306",
	"owner": {
		"displayName":"admin",
		"name":"admin"
	}
}

If successful, the Bitbucket Data Center instance will respond with a 202 and will return a response JSON similar to the one above. The  unlockToken should be used in all subsequent requests where  $BITBUCKET_LOCK_TOKEN  is required. This token can also be used to manually unlock the instance.

バックアップ プロセスの開始

次に、データベースとファイルシステムの両方へのすべてのコネクションを、ドレインおよびラッチする必要があります。コードでファイルシステムとデータベースの両方のバックアップを処理する必要があります。

At this point, you should make a POST request to /mvc/admin/backups. Notice that the curl call includes the ?external=true parameter:

curl -s \
	 -u ${BITBUCKET_BACKUP_USER}:${BITBUCKET_BACKUP_PASS} \
	 -X POST \
	 -H "X-Atlassian-Maintenance-Token: ${BITBUCKET_LOCK_TOKEN}" \
	 -H "Accept: application/json" \
	 -H "Content-type: application/json" \
	 "${BITBUCKET_URL}/mvc/admin/backups?external=true"

{
	"id":"d2e15c3c2da282b0990e8efb30b4bffbcbf09e04",
	"progress": {
		"message":"Closing connections to the current database",
		"percentage":5
	},
	"state":"RUNNING",
	"type":"BACKUP",
	"cancelToken":"d2e15c3c2da282b0990e8efb30b4bffbcbf09e04"
}

成功すると、インスタンスは 202 で応答し、上記のようなレスポンス JSON を返指す。cancelToken は、バックアップ プロセスを手動でキャンセルする際に使用できます。

インスタンスの準備が完了するまで待ちます。

バックアップ プロセスの一環には、データベースおよびファイルシステムへのコネクションのドレインおよびラッチが含まれます。バックアップを続行する前に、この手順が完了したことをインスタンスが報告するのを待機する必要があります。現在のステータスの詳細を確認したい場合、/mvc/maintenance REST ポイントに GET リクエストを行います。

curl -s \
	 -u ${BITBUCKET_BACKUP_USER}:${BITBUCKET_BACKUP_PASS} \
	 -X GET \
	 -H "X-Atlassian-Maintenance-Token: ${BITBUCKET_LOCK_TOKEN}" \
	 -H "Accept: application/json" \
	 -H "Content-type: application/json" \
	 "${BITBUCKET_URL}/mvc/maintenance" 

 {
	"task":{
		"id":"0bb6b2ed52a6a12322e515e88c5d515d6b6fa95e",
		"progress":{
			"message":"Backing up Bitbucket home",
			"percentage":10
		},
		"state":"RUNNING",
		"type":"BACKUP"
	},
	"db-state":"DRAINED",
	"scm-state":"DRAINED"
}

This causes the Bitbucket Data Center instance to report its current state. We have to wait for both  db-state  and  scm-state  to have a status of  DRAINED  before continuing with the backup.  

実際のバックアップの実行

この時点で、ファイルシステムの実際のバックアップを作成する準備が整いました。たとえば、もう一度 rsync を使用できます。

rsync -avh --delete --delete-excluded --exclude=/caches/ --exclude=/data/db.* --exclude=/export/ --exclude=/log/ --exclude=/plugins/.*/ --exclude=/tmp --exclude=/.lock ${BITBUCKET_HOME} ${BITBUCKET_BACKUP_HOME}

ここに示す rsync オプションは例に過ぎませんが、バックアップ プロセスに必要なファイルのみを含め、それ以外を除外する方法を示しています。詳細な説明については、rsync またはお好きなツールのドキュメントを参照してください。 

データベース バックアップを作成する際には、ベンダー固有のバックアップ ツールを使用できます。たとえば、PostgreSQL を使用している場合は　pg_dump を使用できます。

pg_dump -Fd ${BITBUCKET_DB} -j 5 --no-synchronized-snapshots -f ${BITBUCKET_BACKUP_DB}

これらの操作を実行する際は、バックアップの進捗でインスタンスを更新し、進捗を UI で確認できるようにすることをおすすめします。これを行うには、トークンと完了済みのパーセント値をパラメーターとして使用し、/mvc/admin/backups/progress/client に POST リクエストを発行します。

curl -s \
	 -u ${BITBUCKET_BACKUP_USER}:${BITBUCKET_BACKUP_PASS} \
	 -X POST \
	 -H "Accept: application/json" \
	 -H "Content-type: application/json" \
	 "${BITBUCKET_URL}/mvc/admin/backups/progress/client?token=${BITBUCKET_LOCK_TOKEN}&percentage=${BITBUCKET_BACKUP_PERCENTAGE}"

Bitbucket Data Center will respond to this request with an empty 202 if everything is OK. 

When displaying progress to users, Bitbucket Data Center divides the 100 percent progress into 90 percent user DIY Backup, and 10 percent application preparation. This means, for example, if your script sends percentage=0, Bitbucket Data Center may display up to 10 percent progress for its own share of the backup work. 

(オプション) インスタンスに接続されている各 Bitbucket Mesh ノードに Backup スクリプトを実行する

Bitbucket Mesh を使用してリポジトリを保存している場合は、適切なオプションを設定し、各 Mesh ノードで 個別に バックアップスクリプトを実行して、上記のプロセスを繰り返す必要があります。

Inform the Bitbucket Data Center instance that the backup is complete

Once we've finished the backup process we must report to the Bitbucket Data Center instance that progress has reached 100 percent. This is done using a similar request to the progress request. We issue a POST request to /mvc/admin/backups/progress/client with the token and 100 as the percentage:

curl -s \
	 -u ${BITBUCKET_BACKUP_USER}:${BITBUCKET_BACKUP_PASS} \
	 -X POST \
	 -H "Accept: application/json" \
	 -H "Content-type: application/json" \
	 "${BITBUCKET_URL}/mvc/admin/backups/progress/client?token=${BITBUCKET_LOCK_TOKEN}&percentage=100"

Bitbucket Data Center will respond with an empty 202 if everything is OK. The back up process is considered completed once the percentage is 100. This will unlatch the database and the filesystem for this Bitbucket Data Center instance.  

Unlock the Bitbucket Data Center instance 

バックアップ プロセスで行う必要がある最後の手順は、インスタンスのロックを解除することです。これは、/mvc/maintenance/lock REST ポイントへの DELETE リクエストで実施します。

curl -s \
	 -u ${BITBUCKET_BACKUP_USER}:${BITBUCKET_BACKUP_PASS} \
	 -X DELETE \
	 -H "Accept: application/json" \
	 -H "Content-type: application/json" \
	 "${BITBUCKET_URL}/mvc/maintenance/lock?token=${BITBUCKET_LOCK_TOKEN}"

The Bitbucket Data Center instance will respond to this request with an empty 202 if everything is OK, and will unlock access.