This page describes how to upgrade to a new version of Crucible.
- For the latest Crucible release, see Crucible releases.
- Read about how your Crucible installation works with FishEye.
- For production environments we recommend that you test the Crucible upgrade on a QA server before deploying to production.
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:
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.
- 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.
- Read the Supported platforms page for the full list of supported platforms for Crucible.
- Download the Crucible zip file.
- 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.
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 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
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
Method 2: Without a FISHEYE_INST directory
Method 3: Without a FISHEYE_INST directory, but would like to set one up
Upgrading to Crucible 3.2
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:
<a class="anchor-post" href="#" data-href="./fsscm?name=TEST&delete=true">Delete</a>
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
- Communication with JIRA versions older than 5.0 is no longer supported.
- Microsoft SQL Server 2012 is now supported (support for SQL Server 2005 is deprecated).
- Microsoft Internet Explorer 10 is now supported (support for IE 8 is deprecated).
- MySQL 5.0 is deprecated.
- PostgreSQL 8.2 is deprecated.
- The Atlassian AUI plugin has been upgraded to AUI 5.2.
- jQuery has been upgraded to 1.8.3.
- backbonejs has been upgraded to 1.0.
Known issues for Crucible 3.2
Type | Key | Summary | Status |
---|---|---|---|
![]() |
CRUC-6158 | Review performance in IE 8&9 is pathetic |
![]() |
![]() |
CRUC-6485 | Indicate that the listing of reviewers is truncated in the Edit Details view |
![]() |
Upgrading to Crucible 3.1
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:
- Recommended: As an upgrade task that is run automatically when Crucible 3.1 is run for the first time.
- 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
Upgrading to Crucible 3.0
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
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.