• 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 install directory>  is the location of the Fisheye/Crucible application files.

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

Fisheye 4.7 upgrade notes

Several old versions of databases, Git and Mercurial have been deprecated. While they are still supported by Fisheye 4.7 we recommend their upgrade. See end of platform announcements for details.

In case you host Fisheye on 32-bit Windows, we recommend migration to the 64-bit version as Fisheye 4.7 is the last version with the 32-bit installer.

In case you run Fisheye with MySQL database, we recommend migration to UTF8MB4 encoding in order to have support for full UTF8 character set.

In case you use SQL Server database with a bundled driver, Fisheye 4.7.1 will automatically migrate from jTDS to Microsoft JDBC driver. The database URL will change from 'jdbc:jtds:sqlserver' to 'jdbc:sqlserver' scheme. In case you use any custom connection parameters, please make sure the new Microsoft JDBC driver supports them. You can check application logs for any upgrade-related warnings.

In case you have any third party plugins installed, please check their compatibility with Fisheye 4.7, as underlying Jetty server has been upgraded (change of Jetty mainly affects JSP files). The HTTP PUT method is not allowed for JSP files - use POST instead. The HTTP GET shall not use the 'Content-encoding' property.

The rest-service-fe/server-v1 REST endpoint has been removed, use the rest-service-fecru/server-v1 instead.

Fisheye 4.4 upgrade notes

Please also see:

• The general Upgrade steps section above.
• The Fisheye 4.4 Release Notes.
• The Fisheye Supported platforms page.

Mercurial 4.1 and Git 2.12 are supported

Fisheye 4.4 supports Mercurial 4.1 and  Git 2.12 clients

Mercurial 1.5 - 1.8.4 is no longer supported

As of Fisheye 4.4, the oldest Mercurial version supported is 1.9.3 (released in 2011).  Before you upgrade to Fisheye 4.4, upgrade Mercurial client binaries.

Known issues for Fisheye 4.4

Fisheye 4.2 upgrade notes

Please also see:

• The general Upgrade steps section above.
• The Fisheye 4.2 release notes.
• The Fisheye Supported platforms page.

Support for repository renaming

For Fisheye 4.2, and later versions, each repository is now identified by both a (display) name and a key. The name can be changed, even for existing repositories, while the key can never be changed. Previously, repositories were identified only by an immutable 'name' attribute (equivalent to the 'key' attribute in Fisheye 4.2). See Renaming a repository for more details.

When upgrading to Fisheye 4.2, each repository's 'name' will be used to populate both its (display) name and key.

Known issues for Fisheye 4.2

Fisheye 4.1 upgrade notes

Please also see:

• The general Upgrade steps section above.
• The Fisheye 4.1 release notes.
• The Fisheye Supported platforms page.

Subversion 1.9 is supported

Fisheye 4.1 supports Subversion 1.9 and the new FSFS format 7 introduced by this release. You may add new Subversion 1.9 repositories to Fisheye as well as upgrade (with 'svnadmin upgrade' command) repositories that you've already added. Subversion 1.9 support covers both bundled SVN client (SVNKit) as well as Subversion 1.9 native library setup.

Please note however that during internal performance tests we've observed some indexing slowdowns when SVN 1.9 (FSFS format 7) repositories were accessed via file:// protocol using bundled SVN client (comparing to SVN 1.8 ones). Therefore if indexing time is a priority for you, it's recommended to stick to 1.5 - 1.8 repositories, if possible. 

Subversion 1.1 - 1.4 is no longer supported

As of Fisheye 4.1 the lowest Subversion version supported is 1.5 (released in 2008). This applies also to repository format: the lowest supported is format 5 and FSFS format 3. Therefore before you upgrade to Fisheye 4.1, please upgrade both Subversion client/server binaries as well as your repositories (using 'svn upgrade' command). 

Subversion merges are supported

Fisheye 4.1 supports merge operation in Subversion. You may merge branches in Subversion and see information about this in commit graph and on changeset page. More information is available on official documentation page.

Please note that merge information are being processed only for new changesets. Repository history won't be rescanned in order to expose merge for old changesets, however, if you need such historical information, you can perform full repository reindex.

Known issues for Fisheye 4.1

Fisheye 4.0 upgrade notes

Please also see:

• The general Upgrade steps section above.
• The Fisheye 4.0 release notes.
• The Fisheye Supported platforms page.

User directories migration

Fisheye 4.0 includes new user directories administration. Please refer to Fisheye 4.0 user directories migration for details of how users-related settings are migrated.

API changes for plugin developers

Please note that if you're not a plugin developer, changes described in this section will not affect you.

Plugins System 4.0 upgrade

Fisheye 4.0 ships with an upgraded Plugins System. Please refer to the Atlassian Plugins 4.0 Upgrade Guide for a detailed list of changes introduced by the upgrade.

FishEye API changes

Fisheye API changes in Fisheye 4.0 are mainly related to the introduction of user directories. Host-based authentication has been removed, and LDAP-based authentication is now handled by Crowd rather than directly by Fisheye, resulting in the removal of the HostAuthSettings and LdapAuthSettings classes. You could implement a custom authenticator for Fisheye or a custom directory connector for Crowd, if absolutely necessary, but we strongly recommend that you rely on existing authentication methods.

The UserService# getActiveUserCount method is deprecated - use the getLicensedUserCount instead.

You can no longer call UserService# setCrucibleEnabledForUsers to enable Crucible access for certain users, as this method has been removed. Instead, you should assign users to a proper group and set group permissions using the new GlobalPermissionService# setPermissionsForGroup method.

The REST API has minor changes related to user and group management. See the documentation for more details.

Dropping Host-based Authentication 

As already announced, host-based authentication is no longer supported by Fisheye 4.0 and later versions.

Known issues for Fisheye 4.0

Fisheye 3.10 upgrade notes

Please also see:

• The general Upgrade steps section above.
• The Fisheye 3.10 release notes.
• The Fisheye Supported platforms page.

Uppercase project keys upgrade task

The project key upgrade task runs on startup after upgrading to Fisheye 3.10. This is required because Fisheye 3.10 now only allows uppercase project keys; the task should only take a few seconds to run.

• All existing project keys will be converted to be all uppercase and all unique. For Fisheye, this also includes the project key part of review keys.
• If a project key conflict occurs, the project key will be renamed by adding an UPGRADE[Number] suffix. You can change renamed project keys manually after the upgrade if necessary.
• The upgrade task produces logs for project key changes. Look for logs starting with [projectKey.uppercase]
• All operations using the project key as an argument are case sensitive, with the exception that view operations in the browser are case insensitive and will upper case the project key automatically.
• Fisheye and Crucible track recently visited projects, reviews and snippets for every user. Any projects, reviews and snippets with renamed project keys however will not appear in the recently visited cache. 

If there are entity links between JIRA Software and Crucible projects, the mapping will be automatically updated. You can check this by visiting

Administration > Add-ons > Fisheye configuration > Fisheye/Crucible entity mappings in JIRA. If Crucible projects are not all uppercased, click Refresh cache to update the mapping. 

Note that Fisheye and Crucible will refuse to start if the DB is not case-sensitive with UTF-8 default encoding, to avoid potential data corruption during the upgrade task. In this case you'll see the following log message:

FeCru connecting to DB not using case-sensitive UTF8 encoding

Secure connections using self-signed certificates may fail

Fisheye 3.10 uses an updated version of commons-httpclient that provides SNI (Server Name Indication) support. However, this version of commons-httpclient uses stricter domain name verification, so webhooks and application links that use a secure connection may stop working.  This is only likely to happen when Fisheye accesses an application using a secure connection verified by a self-signed certificate, where the application domain name (for example 'jira.company.com') does not match the certificate common name (such as 'company.com').

You may need to update the SSL certificates you use with secure connections between Fisheye 3.10 and other applications – self-signed certificates may no longer work as before.

LDAP synchronization

Fisheye 3.10 now  supports paging (with a default page size of 1000) when requesting data from the LDAP server, and works seamlessly when the number of user accounts exceeds 1000 in Active Directory.  It  reverts to the previous behavior with servers that don't support LDAPv3.

The paging size can be controlled with the  fisheye.ldap.sync.page.size system property. Setting it to 0 disables paging.

Known issues for Fisheye 3.10

Fisheye 3.9 upgrade notes

Please also see:

• The general Upgrade steps section above.
• The Fisheye 3.9 release notes.
• The Fisheye Supported platforms page.

Smart Commits now use the JIRA REST API

As of version 3.9.0, Fisheye uses the JIRA REST API instead of the JIRA Fisheye Plugin for JIRA Smart Commits. This change ensures that you will be able to use Smart Commits with future versions of JIRA. Note that using Smart Commits with previous versions of Fisheye (earlier than 3.9.0) and JIRA 7 will cause an error notification via email. 

Git clone changes

As of version 3.9.0, Fisheye turns Git garbage collection off when cloning a repository (by adding the gc.pruneExpire=never option) to prevent unreferenced objects being removed from local clones. Also, when cloning a repository, git config is run on each repository during instance startup. This change bumps the Git cache version ( CACHE_VERSION ) to 22.

Supported platform upgrades

• Oracle 12c is now supported.
• Git 2.4.6 and Mercurial 3.4.2 are now supported.
• Support for Java 7 has been removed from Fisheye 3.9, as previously announced.
• Support for Internet Explorer 9 has been removed from Fisheye 3.9, as previously announced.

Known issues for Fisheye 3.9

Fisheye 3.8 upgrade notes

Please also see:

• The general Upgrade steps section above.
• The Fisheye 3.8 release notes.
• The Fisheye Supported platforms page.

Improved Git indexing time for newly created branches

In order to allow faster Git indexing, a new field was added to the internal repository caches. The cache for each Git repository is automatically upgraded when the repository is started for the first time after upgrading. It is expected to take  under a minute per repository , but may take slightly longer if repositories have thousands of branches.

Supported platform upgrades

• Java 7 is deprecated, as previously announced.

Known issues for Fisheye 3.8

Fisheye 3.7 upgrade notes

Please also see:

• the general Upgrade steps section above.
• the Fisheye 3.7 release notes.
• the Fisheye Supported platforms page.

Supported platform upgrades

• Java 7 support is deprecated – please see the End of Support Announcements for Fisheye.

Known issues for Fisheye 3.7

Fisheye 3.6 upgrade notes

Please also see:

• the general Upgrade steps section above.
• the Fisheye 3.6 release notes.
• the Fisheye Supported platforms page.

Supported platform upgrades

• Java 6 is not supported by Fisheye 3.6, as previously announced.
• Java 7 support is deprecated – please see  the  End of Support Announcements for Fisheye . 

SSLv3 support is disabled by default

As of Fisheye 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 Fisheye 3.6

Fisheye 3.5 upgrade notes

Please also see:

• the general Upgrade steps section above.
• the Fisheye 3.5 release notes.
• the Fisheye Supported platforms page.
• the End of Support Announcements for Fisheye.

Known issues for Fisheye 3.5

Fisheye 3.4 upgrade notes

Please also see the Upgrade steps section above.

Please read the End of Support Announcements for Fisheye. See Supported platforms.

Windows installer

We've produced 32-bit and 64-bit installers for Fisheye on Windows. Each installer adds Fisheye 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 Fisheye on Windows for detailed installation instructions.

Download the Fisheye installer here.

Git manifest upgrade task

The Git manifest upgrade affects Git repositories. The rationale for the Git manifest change is described in Git manifest. There are two options that may be selected to control how the upgrade is performed. For medium to small sized Git repositories, we expect this upgrade process to be quite fast, in the order of minutes. For very large Git repositories, this could take up to a few hours.

Pre-indexing upgrade

By default, prior to indexing, each Git repository will be upgraded to add the manifest information for all changesets currently in the repository. While this upgrade is in progress, the repository may be browsed normally and any existing reviews will be available for normal review workflow operations. New changesets will not be indexed, and will not be available for review until after the upgrade is complete.

Background upgrade

A background upgrade is performed during the normal repository indexing process. If there is time available within the polling interval, manifest upgrades are performed during the remaining time of the polling interval. The objective is that the next indexing poll should not be delayed unduly so new changesets continue to be indexed normally. The fisheye.manifest.upgradebatch system property is provided to control the minimum number of changesets that should be upgraded in each indexing poll. This is to ensure the background upgrade makes significant progress and may mean the indexing poll interval is longer than configured.

If repositories are configured to not poll, or they have a long polling period, Fisheye will use the default Git polling period for the duration of the upgrade to ensure sufficient indexing occurs. 

While the upgrade is in progress, new changesets will be processed using the existing pre-3.4.0 approach, using Git ls-tree. Only once the upgrade is complete, will the new 3.4.0+ manifest approach be used. This means that the improved performance of the 3.4.0+ manifest upgrade will only be realized once the process is complete.

Choosing an upgrade approach

The upgrade approach that is used by Fisheye is controlled by the fisheye.manifest.forceupgrade  system property – see JVM system properties for information about how to use system properties. The upgrade approach selected applies to the whole Fisheye instance and affects all Git repositories in the instance. It is not possible to choose different upgrade approaches for different repositories.

The default setting of the property is to perform the upgrade prior to resuming normal indexing and this is the approach that we recommend. This realizes the benefits of the new manifest code as soon as possible but it does impact indexing of new changesets. To minimize the impact of such an upgrade, the upgrade could be undertaken during a low traffic period or the upgrade could be performed off-line on a separate server.

If it not feasible to have indexing of new changesets delayed at all, then the background upgrade approach can be used. The fisheye.manifest.upgradebatch system property can be tuned to reduce the amount of time spent upgrading to further reduce new changeset indexing impact.

It also possible to change from one approach to the other until the upgrade is complete. Fisheye records the upgrade progress so that if Fisheye is stopped during an upgrade, the upgrade will resume at the next opportunity. So, if you have started the upgrade using the pre-indexing approach, you can stop the Fisheye server, change the system property, restart and the upgrade will continue using the background upgrade approach. Changing from background upgrade to pre-indexing upgrade is also supported.

Fisheye may now bind to a different IP address on Windows

Prior to Fisheye 3.4, a bug in Fisheye ( FE-4909 - Getting issue details... STATUS ) meant that Fisheye may not have correctly bound to the IP address you configured. This may have happened if you configured Fisheye to bind to a single IP address on a network interface that has several IP addresses; Fisheye 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 Fisheye to use 1.2.3.5, it may have incorrectly bound to 1.2.3.4.

Now that the bug is fixed, Fisheye 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 Fisheye 3.4

Fisheye 3.3 upgrade notes

Please also see the Upgrade steps section above.

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

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

Please read the End of Support Announcements for Fisheye.

Supported platform upgrades

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

See Supported platforms.

Known issues for Fisheye 3.3

Fisheye 3.2 upgrade notes

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

Please note the following changes in Fisheye 3.2:

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.

See Supported platforms.

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.

Known issues for Fisheye 3.2

Fisheye 3.1 upgrade notes

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

Please note the following changes in Fisheye 3.1:

Native SVN access via JavaHL requires JavaHL 1.7

You do not need to upgrade your subversion repositories to 1.7. SVN 1.6 is still supported.

If you are using native JavaHL to connect to your SVN repositories you may need to upgrade the SVN JavaHL client on your Fisheye server. Please read Native support for SVN for more information.

If you are using SVNKit (the default) you do not need to upgrade SVN.

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

Fisheye 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 Fisheye 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 Fisheye 3.1 is run for the first time.
2. As an offline process on a separate staging server.

During the automatic upgrade task, Fisheye 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 Fisheye 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 Fisheye 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 Fisheye 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 Fisheye 3.1

Fisheye 3.0 upgrade notes

Please also see the Upgrade steps section above.

Please note the following changes in Fisheye 3.0:

Jetty 8

Fisheye 3.0 now uses Jetty 8 as its web server and Java servelet container. This change should be completely transparent when you upgrade to Fisheye 3.0. However, if you have customized 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

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

Pipelined indexing

Fisheye 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 Fisheye functionality, such as repository browsing, 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 Fisheye logs and admin screens.

Known issues for Fisheye 3.0