This documentation relates to an earlier version of FishEye.
View

Unknown macro: {spacejump}

or visit the current documentation home.

This page describes the recommended method of upgrading to a new version of FishEye.

The first time you run a new version of FishEye, it will automatically upgrade its data. This may involve a complete re-index of your repository.

On this page:

Before You Start

  • Back up your entire FishEye instance (see Backing Up and Restoring FishEye Data), i.e.
    • If you are backing up your FishEye instance via the Admin interface, tick all of the 'Include' checkboxes (e.g. repository and application caches, plugins and their configuration data, SQL database, etc).
    • If you are backing up your FishEye instance using the command-line interface, do not use any exclusion options.
  • Read the Release Notes and Changelog and version-specific Upgrade Guide 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.
  • Check for known issues in the FishEye Knowledge Base.

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 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.

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, 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:

  1. Shut down your existing FishEye/Crucible server.
  2. Make a backup of your FISHEYE_INST directory.
  3. Extract the new FishEye/Crucible version to a directory, leaving your FISHEYE_INST environment variable set to its existing location.
  4. Start FishEye/Crucible from the new installation
  5. Follow any version-specific instructions found in the FishEye Release Notes/Crucible releases.

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.

  1. Extract the new FishEye/Crucible instance into a directory such as /NEW_FISHEYE/.
  2. Delete the /NEW_FISHEYE/var and /NEW_FISHEYE/cache directories.
  3. Shut down the old FishEye/Crucible instance if it is running.
  4. Copy /OLD_FISHEYE/config.xml to /NEW_FISHEYE/.
  5. Copy (or move) the /OLD_FISHEYE/var directory to /NEW_FISHEYE/var.
  6. Copy (or move) the /OLD_FISHEYE/cache directory to /NEW_FISHEYE/cache.
  7. Copy the /OLD_FISHEYE/data directory to /FISHEYE_INST/data ((info) If your data folder is inside /OLD_FISHEYE/var, keep it inside folder var so that its final location can be /FISHEYE_INST/var/data).
  8. If you have a Cenqua-issued FishEye/Crucible license, copy your fisheye.license to /NEW_FISHEYE/. Atlassian-issued licenses are included within config.xml.
  9. Start FishEye/Crucible from the new installation.
  10. Follow any version-specific instructions found in the FishEye Release Notes/Crucible releases.

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:

  1. Shut down the old FishEye/Crucible instance if it is running.
  2. Set up the FISHEYE_INST environment variable, then create the FISHEYE_INST directory on your filesystem.
  3. Copy the /OLD_FISHEYE/config.xml to /FISHEYE_INST.
  4. Copy the /OLD_FISHEYE/var directory to /FISHEYE_INST.
  5. Copy the /OLD_FISHEYE/cache directory to /FISHEYE_INST.
  6. Copy the /OLD_FISHEYE/data directory to /FISHEYE_INST ((info) If your data folder is inside /OLD_FISHEYE/var, keep it inside folder var so that its final location can be /FISHEYE_INST/var/data). .
  7. Extract the new FishEye/Crucible archive into a directory such as /NEW_FISHEYE/.
  8. Start FishEye/Crucible from the new installation by running NEW_FISHEYE/bin/run.sh. (Use run.baton 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 and FISHEYE_INST. Check your FISHEYE_INST is pointing to the right directory.
  9. Follow any version-specific instructions found in the FishEye Release Notes/Crucible releases.

Checking for Known Issues and Troubleshooting the FishEye Upgrade

If something is not working correctly after you have completed the steps above to upgrade your FishEye installation, please check for known FishEye 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 FishEye after we have released the software. In such cases we publish information about the known issues in the FishEye Knowledge Base. Please check the Fisheye 2.7 Known Issues in the FishEye Knowledge Base and follow the instructions to apply any necessary patches if necessary.
  • Did you encounter a problem during the FishEye upgrade? Please refer to the guide to troubleshooting upgrades in the FishEye 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.

6 Comments

  1. Rene Verschoor

    Jun 16, 2011

    It might be useful to add a note for Windows wrapper users.
    They need to configure their wrapper.conf again, e.g. add FISHEYE_INST and any JVM memory settings.

    1. user-4c0a8

      Feb 10, 2012

      Hi Rene,

      You're right. I had to migrate the wrapper and its configuration too...

      My suggestion to avoid issues on restarting Fisheye/Crucible is to use a Diff-Viewer to compare both the old and the new directories.
      Since not all files/dirs should be compared, it may be usefull to filter the diffs.
      A filter for "WinMerge" could be:

      ## This is a directory/file filter template for WinMerge
      name: ATLASSIAN UPDATES
      desc: Filter some files out (jar, gz, log...)

      ## Select if filter is inclusive or exclusive
      ## Inclusive (loose) filter lets through all items not matching rules
      ## Exclusive filter lets through only items that match to rule
      ## include or exclude
      def: include

      ## Filters for filenames begin with f:
      ## Filters for directories begin with d:
      ## (Inline comments begin with " ##" and extend to the end of the line)

      f: \.dll$
      f: \.js$
      f: \.jar$
      f: \.gz$
      f: \.log$
      f: \.html$
      f: \.class$
      f: \.bin$
      f: \.lastmodified$
      f: \.lck$
      f: \.lock$
      f: \.sh$
      f: \.symbolMap$
      f: \.zip$


      ## Sample fo subdir exclusion (def:include) or inclusion (def:exclude)
      ## d: \\SampleSubDir$ ## Filter for directory "SampleSubDir"

      Cheers,
      L.

  2. Anonymous

    Sept 09, 2011

    Running into issues when upgrading from Fisheye 2.1 to 2.7. Here is an exception

    2011-09-09 10:43:09,826 WARN  [IncrementalPinger1] fisheye.app com.cenqua.fisheye.cvsrep.cache.RepositoryIndex-indexContents - could not index contents of tibco/bw/WSRB/src/WebServiceRequestBroker_Backend/BusinessService/BidSet - MarketTransactionsImpl.process 1.8. Revision contents not indexed
    com.cenqua.fisheye.rep.DbException: java.io.FileNotFoundException: /fecru-2.1.3/var/cache/eint/idx1/_htc.fdt (No such file or directory)

  3. Michael Downey

    Sept 16, 2011

    If I back up through the application web interface and choose all checkboxes, isn't that doing the same thing as backing up the FISHEYE_INST directory? Is this redundant?

  4. Cyrill Gross

    Oct 18, 2011

    IMPORTANT for those using JIRA-integrated user management:
    It might take some time after performing the upgrade until you are able to log in since FishEye might need to re-sync the users first.
    The Duration depends on the Sync-Interval you set under "Administration" > "Security Settings" > "Authentication" > "JIRA or Crowd Authentication" > "

  5. Tim

    Feb 22, 2012

    Important note:

    If you haven't updated your licence file in a while - then simply copying to the new install directory will try and start Fisheye with the old licence. It will fail hard.

    You'll get a HEAP of errors "Licence invalid" in the /var/log/ directory. Of course, I was WTF ? How can I issue a new licence if I don't know the Server-ID fail ?

    If you're in this bind like I was, you should REMOVE the <licence> tags in your config.xml when you are copying over the directory. Then when you run the /bin/run.bat file (since I am on windows) you'll get the Server-ID spat out - which you can use to generate your new licence and the upgrade will work (smile)

    SLF4J: See http://www.slf4j.org/codes.html#multiple_bindings for an explanation.
    2012-02-23 00:17:40,232 INFO - FishEye/Crucible 2.7.10 (20120119115142), Built on XXX
    2012-02-23 00:17:40,240 INFO - Starting UpgradeManager ...
    2012-02-23 00:17:42,248 ERROR - Could not find a FishEye or Crucible license.
    2012-02-23 00:17:42,248 ERROR - Please visit http://my.atlassian.com to retrieve an existing
    2012-02-23 00:17:42,248 ERROR - license quote XXXX-XXXX-XXXX-XXXX to obtain a new license
    2012-02-23 00:17:42,249 ERROR - or visit http://www.atlassian.com/fisheye/renew to renew
    2012-02-23 00:17:42,249 ERROR - your license.
    2012-02-23 00:17:46,914 INFO - Starting database...



Log a request with our support team.



Raise an issue for our developers.



See answers from the community.



Blog and update our documentation.

 Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.