Backing up and restoring Crucible data

• Plugins and their configuration data
• SQL database
• Web templates
• Uploaded files and local copies of files under review.
• Repository and application caches.
  Repository and application caches contain temporary data stored from repository scans and library caches that improve startup time. Both will be recreated automatically by re-scanning the source repositories, so the backup files can be reduced by a significant amount by excluding these (if the cost of re-scanning is acceptable).

4. Once you have chosen your options, click Create Backup Now.

Screenshot: The Crucible Backup Screen

The Crucible command line backup process

Your Crucible instance must be running during the backup.

1. Open a command line interface on the Crucible server computer.
2. Navigate to the <Crucible home directory>/bin/ directory.
3. Run the backup command on the command line with the desired options.
4. The backup is created as a new Zip archive file and placed in the FISHEYE_INST/backup/ directory.
   Note that if your Crucible instance uses a custom FISHEYE_INST directory; make sure the environment variable is properly set when running the backup command.

Components of a Crucible backup

The Crucible backup is highly configurable and allows for many different configurations. This table shows the various components of the backup, what they are for and how they can be used.

Note that the backup will always include the configuration data (config.xml), your license file and the Fisheye user data.

Backup command line options

These examples are for use in a Linux-like operating system. When using these commands on Windows, use the file name fisheyectl.bat and use the correct slashes. Run the command from the <Crucible home directory>/bin/ directory.

The basic syntax of the backup command is as follows:

$ ./fisheyectl.sh backup [OPTIONS]

To see inline help for all backup options, run the following command in the <Crucible home directory>/bin/ directory:

$ ./fisheyectl.sh backup --help

Command line examples

These examples are for use in a Linux-like operating system. When using these commands on Windows, use the filename fisheyectl.bat and use the correct slashes. Run the command from the <Crucible home directory>/bin/ directory.

Backing up with compression of 9, quiet mode and setting an output location

$ ./fisheyectl.sh backup --compression 9 -q -f /application_backups/fisheye/20090215.zip

Backup including cache data (also includes all default components)

$ ./fisheyectl.sh backup --cache

Restoring a backup with cache data (also restores all default components)

$ ./fisheyectl.sh restore --cache

Advanced backup command line settings

In some cases it might be preferable to only backup a limited set of items. This could be useful when your instance uses an external database such as MySQL or PostgreSQL and your DBA has already configured automatic backups in the database. The commands below allow this.

Known limitations

Please note that the below limitations are common for any Java based backup tool.

Archives Containing Over 65535 Files
Versions of Java earlier than v1.6 (b25) are incapable of handling zip files that contain more than 65,535 files. The solution for this problem is to either upgrade to a version of Java later than v1.6 (b25), or ensure that the archive does not exceed the threshold (contains less than 65,535 files). The Fisheye cache (not included in backups by default) can be a contributor of many small files. Hence, exclude the cache from backups if this is likely to be a concern.

Archives Larger Than 4GB
Java has trouble reading and writing zip files that are larger than 4GB. As of release 1.5 Java appears capable of reliably creating archives that are over 4GB, but remains unable to extract them. For details see Sun's bug report. Also be aware of the fact that some file systems (including FAT32) have trouble with files larger than 4GB.

As a workaround, make sure you do not create archives that are larger than 4GB. The Fisheye cache (not included in backups by default) can be a contributor of a lot of small files (although these tend to compress very well). If you still want to archive everything and end up with an achive that is too large, consider creating separate backups for the Fisheye cache and uploaded files respectively.

Scheduling Crucible backups

To set a schedule for automatic backups, open the administration screen and click 'Backup' under 'System' on the left navigation bar. The 'Backup' page opens. Now, click the link 'Manage Scheduled Backups' at the bottom of the page. The 'Scheduled Backups' page opens.

On the 'Scheduled Backups' page, click 'Edit' to adjust the backup schedule. Set the desired options and click 'Save'.

The options for scheduled backups are detailed in the table below.

Screenshot: Scheduling Backups in Fisheye and Crucible

Be aware that scheduled backups can fill up disks unless you regularly move or delete old archives.

Restoring Crucible data

Restoring Crucible data from the command line

There is currently no way to restore a backup from the web interface because Crucible must be shut down during a data restore.

1. Install Crucible into a new, empty directory (this must be the same version that the backup was created from, or later).
   Note that you cannot restore data into versions of Crucible which are older than the version that created the backup.
2. Make sure the Crucible instance is not running.
3. Open a command line interface on the Crucible server computer.
4. Run the restore command on the command line with the desired options.
5. The specified elements will be restored.
6. Start the Crucible instance.
7. When using Fisheye integrated with Crucible, you will need to re-index your repositories after restoring data, unless the backup archive was created with the --cache option.

Command line restore options

These examples are for use in a Linux-like operating system. When using these commands on Windows, use the filename fisheyectl.bat and use the correct slashes. Run the command from the <Crucible home directory>/bin/ directory.

The basic syntax of the restore command is as follows:

$ ./fisheyectl.sh restore -f /path/to/backup_2009-10-02_1138.zip [OPTIONS]

To see inline help for all backup options, run the following command in the <Crucible home directory>/bin/ directory:

$ ./fisheyectl.sh restore --help

Restores a Fisheye/Crucible backup instance.
If you are using an external database (as opposed to the default built-in database), make sure the JDBC driver file is present in the FISHEYE_INST/lib directory when running restore.

Advanced command line restore settings

By default, the restore program will restore all items found in the backup archive (so if you included the caches using the --cache option, these will automatically be restored). However, it is possible to only restore a subset of items from the backup, by explicitly specifying the item names on the command line and only those will be restored.

Notes on migrating backup data

When the process restores a SQL database, it looks at the configuration data (config.xml) included in the backup archive to learn which database product was used and how to connect to it. When Crucible uses the built-in HSQLDB database (which is the default), the restored instance will also use that.
However, when the restored instance will use a different database than the backed up instance (for instance, HSQLDB was used at the time the backup was created, but it needs to be restored on MySQL), use the command line options to point the process to the new database.

Command line example: migrating backup data to MySQL

These examples are for use in a Linux-like operating system. When using these commands on Windows, use the filename fisheyectl.bat and use the correct slashes. Run the command from the <Crucible home directory>/bin/ directory.

Restoring to a Crucible instance that uses a different database (ensure the mysql driver jar file is present in the FISHEYE_INST/lib directory)

$ ./fisheyectl.sh restore \
--username john \
--password smith \
--jdbcurl jdbc:mysql://localhost:3306/crucible \
--dbtype mysql \
--file /path/to/backup_2009-10-02_1138.zip