Crucible upgrade guide
This page describes how to upgrade to a new version of Crucible. We strongly recommend that you update Crucible by performing the steps below.
Note that:
- This update process does not perform an in-place upgrade, but installs the new version of Crucible into a fresh installation directory. The new Crucible uses your existing Crucible home directory and external database.
- For production environments we recommend that you test the Crucible update on a QA server before deploying to production.
- You can update from any previous version to the latest version of Crucible.
If you want to migrate Crucible, as well as upgrade, see Migrating and Upgrading Fisheye/Crucible.
1. Review the upgrade notes
There are specific upgrade notes further down this page for each version of Crucible.
You should read the relevant sections for each version between your current version of Crucible and the version you are upgrading to.
2. Backup your Crucible data
Back up your entire Crucible instance (see Backing up and restoring Crucible data):
- If you are backing up your Crucible instance via the Admin interface, tick all of the 'Include' checkboxes (e.g. plugins, templates, uploads, SQL database, etc).
- If you are backing up your Crucible instance using the command-line interface, do not use any exclusion options.
3. Stop Crucible
In a terminal, change directory to the <Crucible home directory>
and run this:
bin/stop.sh
4. Install Crucible
This update process does not perform an in-place upgrade, but installs the new version of Crucible into a fresh installation directory. The new Crucible uses your existing Crucible home directory and external database.
Download the Crucible zip file. On Windows, download the installer. See Installing Crucible on Linux and Mac or Installing Crucible on Windows for detailed installation instructions.
FISHEYE_INST
directory (i.e. "Fisheye instance" directory).- The
FISHEYE_INST
directory is the Fisheye data directory (not the installation directory) and has a location defined by theFISHEYE_INST
environment variable. It is used to keep the Fisheye data completely separate from the Fisheye/Crucible application files. We recommend that you configure Fisheye/Crucible to use aFISHEYE_INST
directory for production instances. Read more aboutFISHEYE_INST
in Installing Fisheye on Windows or Installing Fisheye on Linux and Mac. - The
<FishEye install directory>
Method 1: Using a FISHEYE_INST directory
Method 2: Without a FISHEYE_INST directory
Method 3: Without a FISHEYE_INST directory, but would like to set one up
Method 4: Using the Fisheye Installer for Windows
5. Update any custom configurations
Once the new vesion of Crucible is installed, remember to update any custom configurations in the new version of Crucible, for example your SQL driver and your wrapper.config file.
If you are using MySQL, read about the JDBC driver.
If you currently run Crucible as a Windows service and are installing the new version of Crucible in a new location, you need to uninstall and then reinstall Crucible as a Windows service. Please see Upgrading Fisheye on Windows for instructions.
For Crucible 3.4 and later, on Windows, you can edit the Java VM properties using the tool included in the download. See JVM system properties.
6. Start Crucible
In a terminal, change directory to the <Crucible home directory>
and run this:
bin/start.sh
After a few moments, in a web browser on the same machine, go to http://localhost:8060/
(or, from another machine, type
http://hostname:8060/
, where hostname
is the name of the machine where you installed Crucible).
Version-specific update notes
This section provides specific update notes for each version of Crucible. These notes supplement the primary update guide above.
You should read the relevant sections for each version between your current version of Crucible and the version you are upgrading to.
Checking for known issues and troubleshooting the Crucible upgrade
If something is not working correctly after you have completed the steps above to upgrade your Crucible installation, please check for known Crucible issues and try troubleshooting your upgrade as described below:
- Check for known issues. Sometimes we find out about a problem with the latest version of Crucible after we have released the software. In such cases we publish information about the known issues in the Crucible Knowledge Base. Please check the Fisheye and Crucible Known Issues in the Crucible Knowledge Base and follow the instructions to apply any necessary patches if necessary.
- Did you encounter a problem during the Crucible upgrade? Please refer to the guide to troubleshooting upgrades in the Crucible Knowledge Base.
- If you encounter a problem during the upgrade and cannot solve it, please create a support ticket and one of our support engineers will help you.