Using the Stash Backup Client

動作の仕組み

The Backup Client implements a common and universal way to back up a Stash instance, and does the following:

1. Locks access to the Stash application, the repositories managed by Stash and the Stash database for the entire duration of the back up. This state is called 'maintenance mode'.
2. すべての Git およびデータベース操作が完了したことを確認します。
3. Performs an application-specific backup of the Stash home directory and the Stash database. The backup is generic and does not depend on the server or database configuration. 
4. バックアップ ファイルをローカル ファイルシステムの指定された場所に、1 つの tar ファイルして保管します。 
5. Unlocks Stash from maintenance mode.

A user will get an error message if they try to access the Stash web interface, or use the Stash hosting services, when Stash is in maintenance mode.

The client supports Windows and Linux platforms, and Stash versions 2.7 and higher, but does not provide ways to integrate with your organizations IT policies or processes.

As an indication of the unavailability time that can be expected when using the Stash Backup Client, in our testing and internal use we have seen downtimes for Stash of 7–8 minutes with repositories totalling 6 GB in size. For comparison, using Stash DIY Backup for the same repositories typically results in a downtime of less than a minute.

バックアップ対象

Backup Client は次のすべてのデータをバックアップします。

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

バックアップには次のファイルおよびディレクトリは含まれません。

• export/*
• log/* (監査ログを除く)
• data/db* (DB 内の HSQL データはバックアップされますが、ディスクのファイルはバックアップされません)
• tmp
• plugins ディレクトリ (installed-plugins ディレクトリを除く) 


Note that the caches directory is included in the backup because it contains previously indexed heads. 

Backing up Stash using the client

The Backup Client must be run from somewhere with access to the Stash home directory. Usually, you will run the Backup Client directly on the Stash server.  Run the client with the following command:

java -jar <path/to/stash-backup-client.jar>

Configuration options are kept in the backup-config.properties file that is included with the client – this file is automatically read when the client is run. The properties are fully documented in the backup-config.properties file, but include:

stash.baseUrl

あるいは、次のプロパティをコマンドラインで指定できます。これらは "-D" プレフィックスを持ち、"-jar" パラメーターの前に配置する必要があります。次に例を示します。

java -Dstash.password="admin" -Dstash.user="admin" -Dstash.baseUrl="http://localhost:7990" -Dstash.home=path/to/stash/home -jar stash-backup-client.jar

Cancelling the client backup

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

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

1. ターミナル (または Windows のコマンド プロンプト) でクライアントによって返されるキャンセル トークンをコピーします。
   
   
2. Go to the Stash interface in your browser. Stash will display this screen:
   
   
   
   
3. Click Cancel backup, and enter the cancel token:
   
   
4. [バックアップを取消] をクリックします。

Restoring Stash into the existing DB

This section applies if you intend to perform a restore into the existing DB configuration/technology. Therefore, in this scenario it is assumed the restore is done to the same server as the one in which Stash was originally backed up.

The stash-restore-client.jar will use the JDBC connection configuration contained in your previous backup generated through the usage of the stash-backup-client.jar. That means you won't need to specify the parameters jdbc.driver, jdbc.url, jdbc.user and jdbc.password at the restore time - it will use whatever is configured in stash-config.properties contained in the STASH_HOME within the backup tarball.

When restoring Stash, the restore client must be run on the machine that Stash should be restored to. In order to ensure accidental restores do not delete existing data, the restore client will only restore into an empty home directory and an empty database. So, make sure that these prerequisites are met:

• Stop your Stash instance
• 現在のホーム ディレクトリのコンテンツを削除し、空にします。
• Drop the existing tables in your database so it is empty. The database still needs to exist with the same user/password, and it should be at the same basic configuration same level as described under the "Create the Stash database" section of the corresponding documentation:
  • MySQL
  • Oracle
  • PostgreSQL
  • SQL Server
• Run the restore client.
• Follow the Stash upgrade guide from the Steps #3 - 5

Running the restore client from the command line

java -Dstash.home="path/to/stash/home" -jar stash-restore-client.jar /path/to/original/backup/file

Restoring Stash into a newly created DB 

This section applies if you intend to perform a restore into a newly created DB. This scenario assumes the restore is done to a server different to the one in which Stash was originally backed up.

The restore process is database agnostic, meaning the database you are restoring your backup to could be of a different configuration/technology from the originally backed up database.

The stash-restore-client.jar will use the JDBC connection configuration specified in the parameters jdbc.driver, jdbc.url, jdbc.user and jdbc.password at the restore time. Once the database backup is successfully restored, it will write the specified parameters in the stash-config.properties within the newly restored STASH_HOME - which will, therefore, enable the new instance connect to the restored database once the steps outlined below are followed.

When restoring Stash, the restore client must be run on the machine that Stash should be restored to. In order to ensure accidental restores do not delete existing data, the restore client will only restore into an empty home directory and an empty database. So, make sure that these prerequisites are met:

• Create a brand new empty home directory with the user that is going to run Stash.
• Create the database you want at the same basic configuration level as described under the "Create the Stash database" section of the corresponding documentation:
  • MySQL
  • Oracle
  • PostgreSQL
  • SQL Server
• Run the restore client.
• Follow the Stash upgrade guide from the Steps #3 - 5

Running the restore client from the command line

You can run the restore client from the command line. In this scenario, as you will have created a new database, you will need to specify the new JDBC parameters while running the command so the client will be able to restore your previous database successfully.

この例では、新しく作成された PostgreSQL への復元を行っています。

java -Djdbc.override=true -Djdbc.driver=org.postgresql.Driver -Djdbc.url=jdbc:postgresql://HOSTNAME:PORT/DATABASE -Djdbc.user=stashuser -Djdbc.password=password -Dstash.home="path/to/stash/home" -jar /path/to/stash-restore-client.jar /path/to/original/backup/file

あるいは、backup-config.properties ファイルでこれらのパラメータを構成することもできます。ファイルが現在のワーキング ディレクトリに存在することを確認してください。サンプル ファイルはクライアントに同梱されます。プロパティは、backup-config.properties ファイルに完全に文書化されており、詳細は以下で説明されています。

JDBC プロパティの使用例

jdbc.driver および jdbc.url プロパティの例を以下に示します。