This page describes the recommended method of upgrading to a new version of Crucible.
Read about how your Crucible installation works with FishEye.
On this page:
Before you Start
- Back up your entire Crucible instance (see Backing Up and Restoring Crucible Data), i.e.
- 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.
- Read the Release Notes and Changelog and version-specific Upgrade Guides for the version you are upgrading to, as well as any versions you are skipping.
- Check the Supported Platforms to ensure that your system meets the requirements for the new version.
- Download the Crucible zip file.
Upgrade Procedure
Your upgrade procedure depends on whether you are using aFISHEYE_INST
directory (i.e. "FishEye instance" directory). The FISHEYE_INST
directory is used to store repository data, separate from the installation location of the FishEye/Crucible application. It is not the installation directory. We recommend that you configure FishEye/Crucible to use a FISHEYE_INST
directory for production instances. Read more about FISHEYE_INST
in the FishEye Installation Guide.Method 1 — Using a FISHEYE_INST Directory
If you have FishEye/Crucible configured to use a FISHEYE_INST
directory, then follow the instructions below:
- Shut down your existing FishEye/Crucible server.
- Make a backup of your
FISHEYE_INST
directory. - Extract the new FishEye/Crucible version to a directory, leaving your FISHEYE_INST environment variable set to its existing location.
- Start FishEye/Crucible from the new installation.
- Follow any version-specific instructions found in the FishEye Release Notes/Crucible Release Notes.
Method 2 — No 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:
You will need to copy some files from your old FishEye/Crucible installation to your new one.
- Extract the new FishEye/Crucible instance into a directory such as
/NEW_FISHEYE/
. - Delete the
/NEW_FISHEYE/var
and/NEW_FISHEYE/cache
directories. - Shut down the old FishEye/Crucible instance if it is running.
- Copy
/OLD_FISHEYE/config.xml
to/NEW_FISHEYE/
. - Copy (or move) the
/OLD_FISHEYE/var
directory to/NEW_FISHEYE/var
. - Copy (or move) the
/OLD_FISHEYE/cache
directory to/NEW_FISHEYE/cache
. - Copy the
/OLD_FISHEYE/data
directory to/FISHEYE_INST/data
(If your
data
folder is inside/OLD_FISHEYE/var
, keep it inside foldervar
so that its final location can be/FISHEYE_INST/var/data
). - If you have a Cenqua-issued FishEye/Crucible license, copy your
fisheye.license
to/NEW_FISHEYE/
. Atlassian-issued licenses are included withinconfig.xml
. - Start FishEye/Crucible from the new installation.
- 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:
- Shut down the old FishEye/Crucible instance if it is running.
- Set up the
FISHEYE_INST
environment variable, then create the FISHEYE_INST directory on your filesystem. - Copy the
/OLD_FISHEYE/config.xml
to/FISHEYE_INST
. - Copy the
/OLD_FISHEYE/var
directory to/FISHEYE_INST
. - Copy the
/OLD_FISHEYE/cache
directory to/FISHEYE_INST
. - Copy the
/OLD_FISHEYE/data
directory to/FISHEYE_INST
(If your
data
folder is inside/OLD_FISHEYE/var
, keep it inside foldervar
so that its final location can be/FISHEYE_INST/var/data
). . - Extract the new FishEye/Crucible archive into a directory such as
/NEW_FISHEYE/
. - Start FishEye/Crucible from the new installation by running
NEW_FISHEYE/bin/run.sh
. (Userun.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
FISHEYE_HOME
andFISHEYE_INST
. Check 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
- 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 Crucible 2.6 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.