Crucible data can be backed up from the admin interface or command line. This page contains the command syntax, options and the required procedure to backup and restore your Crucible instance.

If you are migrating to a different machine, please follow the instructions on our Migrating Fisheye Between Servers page.

Backing up using admin interface

1. Navigate to the Crucible Admin area (click the Administration link in the footer of any Crucible page).
2. In the left navigation bar, click Backup.
3. On the Backup screen, you can edit the name of the backup file that will be generated.
4. Choose the components, described in the table below, that should be included in the backup file.
   Note that the back up will always include the configuration data (config.xml), your license file and the Fisheye user data.
    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 significantly reduced by excluding these (if the cost of re-scanning is acceptable).
5. Click Create Backup Now .

Using the command line to back up

Your Crucible instance must be running during the backup.

1. Open a command line interface on the Crucible server computer.
2. Navigate to <Crucible installation dir>/bin/
3. Run the backup command on the command line using any desired options (described in the table below). By default, all backup components, except repository cache data, is included in the backup.

The backup is created as a new Zip archive file and placed in the <Crucible installation dir>/ 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.

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.

Backup 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  <Crucible installation dir>/bin/.

The basic syntax of the backup command is as follows:

$ ./fisheyectl.sh backup [OPTIONS]

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

Known limitations

Archives Larger Than 4GB
Be aware of the fact that some file systems (like FAT32) have trouble with files larger than 4GB. If you still want to archive everything and end up with an archive that is too large, consider creating separate backups for the Crucible cache and uploaded files respectively.

Scheduling Crucible backups

To set a schedule for automatic backups:

1. Go to the Admin area and click Backup (under 'System Settings').
2. Click Manage Scheduled Backups at the bottom of the page.
3. Click Edit, set the desired options, then click Save.

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

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

Restoring Crucible data

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

Using the command line to restore Crucible data 

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

By default, the restore process 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, you can specify a partial restore, by explicitly specifying the item names on the command line.

If you are using an external database (as opposed to the default HSQL database), make sure the JDBC driver file is present in the FISHEYE_INST/lib directory when running restore.

Furthermore, if you are restoring to a new Crucible instance and install directory, and select --dbtype of mysql, you must download the JDBC driver and accept the license agreement before proceeding with the restore.

The options available for use with the restore command are listed in the following table:

 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 <Crucible installation dir>/bin/.

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  <Crucible installation dir>/bin/

$ ./fisheyectl.sh restore --help

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

$ ./fisheyectl.sh restore --cache

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.

Restoring a backup of SQL Server database

Crucible  4.7.1 (and higher) uses new scheme for SQL Server JDBC URL. In order to restore a backup generated from a version prior to 4.7.1, database connection properties (database type, URL, username and password) have to be set explicitly in a command line. Otherwise, restore command will fail as config.xml in the backup file contains an invalid URL scheme.

Change the scheme in the following manner: 

from jdbc:jtds:sqlserver://

to    jdbc:sqlserver://

To use any custom connection parameters, such as domain-based authentication, you have to change them to the ones supported by Microsoft JDBC (see properties supported by jTDS and by Microsoft JDBC). 

Example for Linux operating system:

$ ./fisheyectl.sh restore \
--username 'john' \
--password 'smith' \
--jdbcurl 'jdbc:sqlserver://localhost:1433;databaseName=crucible;' \
--dbtype 'sqlserver2012' \
--file '/path/to/backup_2009-10-02_1138.zip' \
--force

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 ), you should use the command line options to point the process to the new database which must exist before running the restore. The restore will only populate the database, it will not create the database.

Command line example: migrating backup data to MySQL

 This example is 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 <Crucible installation dir>/ bin/

 We recommend to put values in quotes to avoid evaluation of special characters by the shell (e.g. ';' in JDBC URL may be treated as command separator on Linux).

 Use the '--force' option also for an empty database (otherwise restore command won't proceed).

Restoring to a Fisheye 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' \
--force