Skip to end of metadata
Go to start of metadata

This page describes how to upgrade to a new version of Crucible.

On this page:

Upgrade steps

This section provides general instructions for upgrading Crucible. See also the specific notes on this page for the version of Crucible you are upgrading to. We strongly recommend that you upgrade Crucible by following these steps:

  1. Back up your entire Crucible instance (see Backing up and restoring Crucible data):

    1. 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).
    2. If you are backing up your Crucible instance using the command-line interface, do not use any exclusion options.
  2. Read the Release Notes and Changelog and version-specific Upgrade Guides for the version you are upgrading to, as well as for any versions you are skipping.
  3. Read the  Supported platforms  page for the full list of supported platforms for Crucible.
  4. 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.
  5. Update any custom configurations in the new version of Crucible, for example your database JDBC driver jar file and your wrapper.config file, once the new version of Crucible is installed.

If you currently run FishEye or Crucible as a Windows service and are installing the new version of FishEye or Crucible in a new location, you need to uninstall and then reinstall FishEye/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.

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 a FISHEYE_INST directory for production instances. Read more about FISHEYE_INST in Installing FishEye on Windows or Installing FishEye on Linux and Mac.
  • The <FishEye home directory> is the location of the FishEye/Crucible application files.
Method 1: Using a FISHEYE_INST directory
 Click here to expand...

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.

  1. Shut down your existing FishEye/Crucible server, using bin\stop.bat or bin\stop.sh from the <FishEye home directory>.
  2. Make a backup of your FISHEYE_INST directory.
  3. Download FishEye or Crucible.
  4. Extract the new FishEye/Crucible version to a new directory.
  5. 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).
  6. Start FishEye/Crucible from the new installation directory by running bin/run.sh. (Use run.bat on Windows.)
  7. Follow any version-specific instructions found in the FishEye upgrade guide or Crucible upgrade guide.
Method 2: Without a FISHEYE_INST directory
 Click here to expand...

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 <FishEye home directory> 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.

You will need to copy some files from your old FishEye/Crucible installation to your new one.

  1. Download FishEye or Crucible.
  2. Extract the new FishEye/Crucible archive into a directory such as <New FishEye home directory>.
  3. Shut down the old FishEye/Crucible server, using bin\stop.bat or bin\stop.sh from the <FishEye home directory>.
  4. Copy <FishEye home directory>/config.xml to <New FishEye home directory>.
  5. Delete the following directories from the <New FishEye home directory>/var directory:
    • <New FishEye home directory>/var/cache
    • <New FishEye home directory>/var/data
    • <New FishEye home directory>/var/log
  6. Copy (or move) the following directories from <FishEye home directory>/var to <New FishEye home directory>/var:
    • <FishEye home directory>/var/cache
    • <FishEye home directory>/var/data
    • <FishEye home directory>/var/log
    DO NOT include the following directories when you do that:
    • <FishEye home directory>/var/osgi-cache
    • <FishEye home directory>/var/plugins
    • <FishEye home directory>/var/tmp
  7. Delete the <New FishEye home directory>/cache directory.
  8. Copy (or move) the <FishEye home directory>/cache directory to <New FishEye home directory>/cache.
  9. Start FishEye/Crucible from the new installation by running <New FishEye home directory>/bin/run.sh. (Use run.bat on Windows.)
  10. Follow any version-specific instructions found in the FishEye upgrade guide  or Crucible upgrade guide.
Method 3: Without a FISHEYE_INST directory, but would like to set one up
 Click here to expand...

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 <FishEye home directory> is the location of the existing FishEye/Crucible installation.

  1. Download FishEye or Crucible.
  2. Shut down the existing FishEye/Crucible server, using bin\stop.bat or bin\stop.sh from the <FishEye home directory>.
  3. Set up the FISHEYE_INST environment variable, then create the FISHEYE_INST directory on your file system.
  4. Copy <FishEye home directory>/config.xml to the FISHEYE_INST directory.
  5. Copy the <FishEye home directory>/var directory to the FISHEYE_INST directory.
  6. Copy the <FishEye home directory>/cache directory to the FISHEYE_INST directory.
  7. If it exists, copy the <FishEye home directory>/data directory to the FISHEYE_INST directory.
  8. Extract the new FishEye/Crucible archive into a directory such as <New FishEye home directory>.
  9. Start FishEye/Crucible from the new installation by running <New FishEye home directory>/bin/run.sh. (Use 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> and FISHEYE_INST. Check that your FISHEYE_INST is pointing to the right directory.
  10. Follow any version-specific instructions found in the FishEye upgrade guide  or Crucible upgrade guide.
Method 4: Using the FishEye Installer for Windows
 Click here to expand...

Using a FISHEYE_INST directory (including when previously running as a Windows Service using the wrapper)

 Click here to expand...

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. This also applies when previously running FishEye as a Windows Service and the FISHEYE_INST location is defined within the wrapper.

  1. Shut down your existing FishEye/Crucible server, using bin\stop.bat or bin\stop.sh from the <FishEye home directory>.
    If you currently run FishEye or Crucible as a Windows service, see Upgrading FishEye on Windows for instructions on uninstalling the service.
  2. Make a backup of your FISHEYE_INST directory.
  3. Download FishEye or Crucible.
  4. Run the installer.
  5. Select the option to use the Custom Install. Proceed with the install.
  6. Select the folder where FishEye will be installed. In this step you can leave the default value selected. Proceed with the install.
  7. Select the folder where your data will be stored, which in this case is the folder pointed by your FISHEYE_INST. Ensure to select the correct folder in order to have all your data being read by FishEye. For example, if your FISHEYE_INST is currently set to C:\Atlassian\fish_inst, this is the folder you have to select. Proceed with the install until the end.
    • 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).
  8. FishEye will be installed and running as a service by the end of the install process.
  9. Follow any version-specific instructions found in the FishEye upgrade guide or Crucible upgrade guide.

Without a FISHEYE_INST directory (including when previously running as a Windows Service using the wrapper)

 Click here to expand...

If you do not have FishEye/Crucible configured to use a FISHEYE_INST directory, the installer will create a directory for you and will create a FISHEYE_INST environment variable pointing to it. In the following instructions, <FishEye home directory> refers to the location of the previous FishEye/Crucible installation. This also applies when previously running FishEye as a Windows Service and there is no FISHEYE_INST defined.

  1. Shut down your existing FishEye/Crucible server, using bin\stop.bat or bin\stop.sh from the <FishEye home directory>.
    If you currently run FishEye or Crucible as a Windows service, see Upgrading FishEye on Windows for instructions on uninstalling the service. 
  2. Download FishEye or Crucible.
  3. Run the installer.
  4. Select the option to use the Default Install. You may also use Custom Install if you want to select the directories where FishEye will be installed and where your data will be stored. Proceed with the install.
  5. FishEye will be installed and running as a service by the end of the install process.
  6. Stop FishEye service (names as Atlassian FishEye).
  7. Copy <FishEye home directory>/config.xml to <FISHEYE_INST>.
  8. Delete the following directories from the <FISHEYE_INST>/var directory:
    • <FISHEYE_INST>/var/cache
    • <FISHEYE_INST>/var/data
    • <FISHEYE_INST>/var/log
  9. Copy (or move) the following directories from <FishEye home directory>/var to <FISHEYE_INST>/var: 
    • <FishEye home directory>/var/cache
    • <FishEye home directory>/var/data
    • <FishEye home directory>/var/log
      DO NOT include the following directories when you do that:
    • <FishEye home directory>/var/osgi-cache
    • <FishEye home directory>/var/plugins
    • <FishEye home directory>/var/tmp
  10. Delete the <FISHEYE_INST>/cache directory.
  11. Copy (or move) the <FishEye home directory>/cache directory to <FISHEYE_INST>/cache.
  12. Start the Atlassian FishEye service.
  13. Follow any version-specific instructions found in the FishEye upgrade guide or Crucible upgrade guide.

Crucible 3.7 upgrade notes

Please also see:

Supported platform upgrades

Known issues for Crucible 3.7

Loading

Crucible 3.6 upgrade notes

Please also see:

Supported platform upgrades

SSLv3 support disabled by default

As of Crucible 3.6, SSLv3 support is disabled by default. This shouldn't affect normal operations in supported browsers. If you need to re-enable SSLv3 support, please consult Configuring SSL cipher suites for Jetty.

Known issues for Crucible 3.6

Loading

Crucible 3.5 upgrade notes

An upgrade from an earlier version of FishEye/Crucible to 3.5.0 may cause problems if you have upgraded the Universal Plugin Manager Plugin to a newer version than is shipped with FishEye/Crucible 3.5.0.

The workaround for this is to remove the custom installed version of the Universal Plugin Manager Plugin.

After upgrading from 3.4.5 to 3.5.0, this error is printed in the web browser when you try to access some pages:

javax.servlet.jsp.JspException: javax.el.ELException: java.lang.NullPointerException: couldn't locate WebResourceIntegration service

Workaround:

  • Stop the new FishEye instance;
  • Remove your newer version of the Universal Plugin Manager Plugin at $FISHEYE_INST/var/plugins/user/plugin.xxxxxx.atlassian-universal-plugin-manager-plugin*.jar;
  • Start the new FishEye instance again.

Please also see:

Known issues for Crucible 3.5

Loading

Crucible 3.4 upgrade notes

Please also see:

Windows installer

We've produced 32-bit and 64-bit installers for Crucible on Windows. Each installer adds Crucible as a Windows service, and starts the service, automatically. The express install creates, by default, a Data directory and a separate install directory  in C:\Atlassian. The custom install mode allows you to choose different locations for the install and Data directories, with the restriction that the Data directory must not be contained in the install directory. The installer creates the FISHEYE_INST system environment variable.

See Installing Crucible on Windows for detailed installation instructions.

Download the Crucible installer here.

Crucible may now bind to a different IP address on Windows

Prior to Crucible 3.4, a bug in Crucible (  FE-4909 CLOSED ) meant that Crucible may not have correctly bound to the IP address you configured. This may have happened if you configured Crucible to bind to a single IP address on a network interface that has several IP addresses; Crucible may in fact have bound to a different IP address. For example, if you have an interface with the IP addresses 1.2.3.4 and 1.2.3.5, and you configured Crucible to use 1.2.3.5, it may have incorrectly bound to 1.2.3.4.

Now that the bug is fixed, Crucible 3.4, and later versions, will now correctly bind to the configured IP address, although this may now be different from the previously bound address.

v1 REST API resources deprecated

Note that the 'v1' REST API resources are deprecated and will be removed in a future release. See the FishEye Crucible REST API.

Known issues for Crucible 3.4

Loading

Crucible 3.3 upgrade notes

Please also see the Upgrade steps section above.

As previously announced, the following platforms are no longer supported by Crucible 3.3:

  • Internet Explorer 8
  • MySQL 5.0
  • PostgreSQL 8.2
  • SQL Server 2005

Please read the End of Support Announcements for Crucible.

Supported platform upgrades

  • SVN 1.8 is supported by Crucible 3.3.
  • Microsoft Internet Explorer 11 is supported by Crucible 3.3.

See the Crucible Supported platforms.

Known issues for Crucible 3.3

Loading

Crucible 3.2 upgrade notes

Please also see the Upgrade steps section above, and read the End of Support Announcements for Crucible page.

Please note the following changes in Crucible 3.2:

REST endpoint change

For Crucible 3.2, the RestReviewService.remindIncompleteReviewers() ('/rest-service/reviews-v1/{reviewId}/remind') end point was changed from accepting 'application/x-www-form-urlencoded' content type with 'message' and 'recipient' params to 'application/json' content type with 'message' and 'recipients' JSON fields. See  https://docs.atlassian.com/fisheye-crucible/latest/wadl/crucible.html#d2e1881.

User data is moved from data0.bin to the SQL database

An upgrade task is run on startup that moves user data to the SQL database. We are doing this to mitigate the risk of data corruption or loss.

XSRF protection

FishEye/Crucible 3.2.0 includes protection against XSRF attacks.

If you have implemented a LightSCM plugin, and have used the SimpleConfigurationServlet base class provided in the scmutils library, you will need to modify your administration page so that it performs 'delete' operations using an HTTP POST, not a GET.

You can have FishEye convert your anchor tags to form POSTs at runtime by giving them the class "anchor-post". For example, the anchor:

will be converted into a form which POSTs to ./fsscm with form parameters name=TEST and delete=true.

Internally managed Git repositories no longer supported

As previously announced, internally managed Git repositories are no longer supported by FishEye 3.2.

Please read the migration guide for information about options and procedures for migrating your internally managed Git repositories – note that we recommend that you upgrade to FishEye 3.2 before migrating any internally managed repositories.

Supported platform upgrades

See the Crucible Supported platforms.

Known issues for Crucible 3.2

Loading

Crucible 3.1 upgrade notes

Please also see the Upgrade steps section above, and read the End of Support Announcements for Crucible page.

Please note the following changes in Crucible 3.1:

Crucible 3.1 Merge some per-repository Lucene indices into a global cross-repository Lucene index

Crucible 3.1 has greatly improved performance and scalability for QuickSearch and QuickNav. To achieve this, the per-repository 'METADATA' Lucene indices will be moved into a single global cross-repository Lucene index. This means Crucible is able to search across more repositories in less time because now only a single search index needs to be queried instead of the previous N. Merging these indices into the single cross-repository index can be refreshed in two ways:

  1. Recommended: As an upgrade task that is run automatically when Crucible 3.1 is run for the first time.
  2. As an offline process on a separate staging server.

During the automatic upgrade task, Crucible is fully usable and functional, although search results for files, commits and committers may be incomplete.

In our testing we have found that the automatic upgrade task took 4 hours to complete on a Crucible instance with 144 repositories of different kinds, with 58 GB of data in the FISHEYE_INST folder (excluding logs). We are confident that the automatic upgrade task is suitable for the majority of production Crucible installations. It is worth repeating that the instance was fully functional (reviews, JIRA Integration, Activity Streams, Charts etc) apart from Quick Nav and Quick Search during this time.

Nevertheless, where required, we provide instructions for performing the reindex as an offline process on a separate staging server.

Plugin Settings will be moved from the config.xml to the SQL database

As of Crucible 3.1.0, plugin settings which were previously stored in the <properties> element inside config.xml will be stored in the SQL database. This includes settings for any bundled plugins such as ApplicationLinks, the UniversalPluginManager etc, and any 3rd party plugins. 

An upgrade task is run on startup which will first insert all the properties found in config.xml into a new table in the SQL database. Once successful, the properties are removed from config.xml. 

As part of this change, the RepositoryOptions.setProperties (Map<String, String>properties) and RepositoryOptions.getProperties() methods have been removed from our API. If you are using a plugin which uses either of these methods, you will need to update the plugin to a version which uses the Spring component PluginSettingsFactory. Plugins can use this to access the migrated global and per-repository properties that were previously available via the old RepositoryOptions API. 

Known issues for Crucible 3.1

Loading

Crucible 3.0 upgrade notes

Please also see the Upgrade steps section above.

Please note the following changes in Crucible 3.0:

Jetty 8

Crucible 3.0 now uses Jetty 8 as its web server and Java servelet container. This change should be completely transparent when you upgrade to Crucible 3.0. However, if you have customised either your jetty-web.xml file, or the maxFormContentSize system property, you will need to update those in the new version. See Enabling Access Logging in FishEye and this FishEye KB page for more information.

Infinity DB

Crucible 3.0 now uses the InfinityDB 3.0 database internally to provide improved performance for concurrent access to Crucible. This change is transparent to users in all respects.

Pipelined indexing

Crucible 3.0 introduces a new indexing approach that splits the repository indexing process into separate tasks that can be performed in a phased and concurrent way. Users will benefit from the way in which Crucible functionality, such as review creation, now becomes available as indexing progresses. This change is transparent to users in all other respects. See Pipelined indexing.

Improved handling of user preferences with session cookies 

Upgrading may result in some users losing their preferences.

SQL Server transaction isolation configuration

We recommend a configuration change for SQL Server to use snapshot mode for the transaction isolation level – see Migrating to SQL Server. This change avoids occasional database deadlocks, and prevents performance warning messages in the logs and admin screens.

Known issues for Crucible 3.0

Loading

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.

3 Comments

  1. Would really like a reminder to re-copy/install the SQL database drivers.  I always forget this. 

  2. Anonymous

    And the wrapper.conf file as well!

  3. JP

    Here is a problem we encountered and a necessary step that escaped me even after reading this page.

    If you are upgrading an existing fisheye/crucible installation which has an existing FISHEYE_INST directory, you need to manually copy your database driver jar file into FISHEYE_INST/lib.  Do this after the installer finishes.  You will need to restart afterward.