This page describes the recommended method of upgrading to a new version of Crucible.
Before you start
|
Upgrade procedure
Your upgrade procedure depends on whether you are using a 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 the FISHEYE_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
is the location of the FishEye/Crucible application files.<FishEye home directory>
NOTE: For all methods below: if you previously ran FishEye as a Windows service and are installing the new version of FishEye in a new location, you need to reinstall FishEye as a Windows service. Make sure to run ...\wrapper\bin\Fisheye-Uninstall-NTService.bat from the old location. Subsequently, prior to starting the new instance of FishEye, follow these instructions to set up Fisheye as a Windows service again. Make sure to copy over the changes from the old ...\wrapper\conf\wrapper.conf file to the new wrapper.conf file.
Method 1: Using a FISHEYE_INST directory
If you have FishEye/Crucible configured to use a FISHEYE_INST
directory, then follow the instructions below. This is the recommended scenario for production installations.
- Shut down your existing FishEye/Crucible server.
- Make a backup of your
FISHEYE_INST
directory. - Download FishEye or Crucible.
- Extract the new FishEye/Crucible version to a new directory.
- Leave your FISHEYE_INST environment variable set to its existing location. Both FishEye and Crucible use this variable.
- Please be aware that jar files in the
FISHEYE_INST/lib
directory may conflict with those required for FishEye's normal operation. Jar files in this directory should be limited to those which provide functionality not provided by FishEye (e.g. database drivers).
- Please be aware that jar files in the
- Start FishEye/Crucible from the new installation directory by running
bin/run.sh
. (Userun.bat
on Windows.) - Follow any version-specific instructions found in the FishEye Release Notes/Crucible Release Notes.
Method 2: Without a FISHEYE_INST directory
If you do not have FishEye/Crucible configured to use a FISHEYE_INST
directory and do not want to set one up, then follow the instructions below. The
is the location of the existing FishEye/Crucible installation. Note that this is the typical scenario for evaluation installations, and is not recommended for production installations.<FishEye home directory>
You will need to copy some files from your old FishEye/Crucible installation to your new one.
- Download FishEye or Crucible.
- Extract the new FishEye/Crucible archive into a directory such as
.<New FishEye home directory>
- Shut down the old FishEye/Crucible instance if it is running.
- Copy
/config.xml to<FishEye home directory>
.<New FishEye home directory>
- Delete the
/var and<New FishEye home directory>
/cache directories.<New FishEye home directory>
- Copy (or move) the
/var directory to<FishEye home directory>
/var.<New FishEye home directory>
- Copy (or move) the
/cache directory to<FishEye home directory>
/cache.<New FishEye home directory>
- Start FishEye/Crucible from the new installation by running
. (Use<New FishEye home directory>
/bin/run.shrun.bat
on Windows.) - Follow any version-specific instructions found in the FishEye Release Notes/Crucible Release Notes.
Method 3: Without a FISHEYE_INST directory, but would like to set one up
If you do not have FishEye/Crucible configured to use a FISHEYE_INST
directory but would like to set one up, then follow the instructions below. You may wish to do this when reconfiguring an existing installation for a production environment.
The FISHEYE_INST
directory is the FishEye data directory, which has a location defined by the FISHEYE_INST environment variable, and which should be completely separate from the <FishEye home directory>
. The
is the location of the existing FishEye/Crucible installation.<FishEye home directory>
- Download FishEye or Crucible.
- Shut down the existing FishEye/Crucible instance if it is running.
- Set up the
FISHEYE_INST
environment variable, then create theFISHEYE_INST
directory on your file system. - Copy
to the<FishEye home directory>
/config.xmlFISHEYE_INST
directory. - Copy the
directory to the<FishEye home directory>
/varFISHEYE_INST
directory. - Copy the
directory to the<FishEye home directory>
/cacheFISHEYE_INST
directory. - Extract the new FishEye/Crucible archive into a directory such as
.<New FishEye home directory>
- Start FishEye/Crucible from the new installation by running
/bin/run.sh. (Use<New FishEye home directory>
run.bat
on Windows.)- If your configuration is not automatically picked up and you cannot see your existing repositories, check your Administration > Sys-Info page, where you will see information about the
<FishEye home directory>
andFISHEYE_INST
. Check that yourFISHEYE_INST
is pointing to the right directory.
- If your configuration is not automatically picked up and you cannot see your existing repositories, check your Administration > Sys-Info page, where you will see information about the
- Follow any version-specific instructions found in the FishEye Release Notes/Crucible Release Notes.
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.