Installing Fisheye on Linux and Mac

Still need help?

The Atlassian Community is here for you.

Ask the community

Hey! We're going to install Fisheye on a Linux box, or a Mac. There are a few steps involved, but we think you'll find it easy to follow along. If you are upgrading an existing installation, please refer to the Fisheye upgrade guide instead.

1. Check supported platforms

Better check the Supported platforms page first; it lists the application servers, databases, operating systems, web browsers and JDKs that we have tested Fisheye with, and that we recommend.

Atlassian only officially supports Fisheye running on x86 hardware and 64-bit derivatives of x86 hardware.

2. Create a dedicated Fisheye user (recommended)

For production installations, we recommend that you create a new dedicated user that will run Fisheye on your system. This user:

  • Should not have admin privileges.
  • Should be a non-privileged user with read, write and execute access on the Fisheye install directory and instance (data) directory. These directories are described below.
  • Should only have read access to your repositories. 

If you created a dedicated Fisheye user, ensure you are logged in as this user to complete the remaining instructions.

3. Check your version of Java

In a terminal, run this:

java -version

The version of Java should be 1.8.x.

If you don't see a supported version of Java, then get Java...

Download and install the Oracle JVM (JDK or JRE), or OpenJDK.

Now try running 'java -version' again to check the installation. The version of Java should be 1.8.x.

4. Check that the system can find Java

In a terminal, run this:

echo $JAVA_HOME

You should see a path like /System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home/.

If you don't see a path to the Java location, then set JAVA_HOME...

Linux

Do either of the following:

  • If JAVA_HOME is not set, log in with 'root' level permissions and run:

    echo JAVA_HOME="path/to/JAVA_HOME" >> /etc/environment

    Where path/to/JAVA_HOME may be like: /System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home/

  • If JAVA_HOME  needs to be changed, open the  /etc/environment  file in a text editor and modify the value for  JAVA_HOME to:
    JAVA_HOME="path/to/JAVA_HOME"

    It should look like:

    JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home/

Mac

Insert the following in your ~/.profile file:

JAVA_HOME="path/to/JAVA_HOME"
export JAVA_HOME

where path/to/JAVA_HOME may be like: /System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home/

Refresh your ~/.profile in the terminal and confirm that JAVA_HOME is set:

source ~/.profile
$JAVA_HOME/bin/java -version

You should see a version of Java that is 1.8.0 or higher, like this:

java version "1.8.0_05"

5. Now it's time to get Fisheye

  1. Download Fisheye from the Atlassian download site.
  2. Please check your unzip program before extracting the downloaded zip file. Some archive-extract programs cause errors when unzipping the Fisheye zip file:
    • Windows users must avoid the Windows built-in unzip utility, as it doesn't extract all the files. Use a third-party unzip program like 7-Zip or Winzip.
    • Solaris users will need to use GNU tar to handle the long file names.
  3. Extract the downloaded file to an install location:
    • Folder names in the path to your Fisheye executable should not have spaces in them. The path to the extracted directory is referred to as the <FishEye install directory> in these instructions.
    • If you expect to have a large number of users for this Fisheye installation, and Fisheye will be connected to an external database, consider installing Fisheye on a different server from the one running the external database, for improved performance.

6. Tell Fisheye where to store your data  

The Fisheye instance directory is where your Fisheye data is stored.

(warning) You should not locate your Fisheye instance directory inside the <FishEye install directory> — they should be entirely separate locations. If you do put the  instance directory in the <FishEye install directory> it will be overwritten, and lost, when Fisheye gets upgraded. And by the way, you'll need separate Fisheye instance directories if you want to run multiple copies of Fisheye.

For production installations, we recommend that the Fisheye instance directory be secured against unauthorized access.

Create your Fisheye instance directory, and then tell Fisheye where you created it by adding a FISHEYE_INST environment variable as follows:

  • LinuxOpen the /etc/environment file in a text editor and insert:

    FISHEYE_INST="path/to/<FishEye instance directory>"
  • Mac: Open the ~/.profile file for the current user in a text editor and insert:

    FISHEYE_INST="path/to/<FishEye instance directory>"
    export FISHEYE_INST

You need to log out and log in again so the new environment variable is set.

Alternatively you can run
export FISHEYE_INST="path/to/<FishEye instance directory>"

to avoid logging out and in.

Now, copy the <FishEye install directory> /config.xml to the root of the FISHEYE_INST directory, so that Fisheye can start properly.

Also, if you have a large number of repositories, we recommend you increase the default number of files that Fisheye is allowed to open. See the following knowledge base article for more info: Subversion Indexer Paused with "Too many open files" Error.

7. Start Fisheye!

In a terminal, change directory to <FishEye install directory> and run this:

bin/start.sh

After a few moments, in a web browser on the same machine, go to http://localhost:8060/ (or, from another machine, type  http://hostname:8060/, where hostname is the name of the machine where you installed Fisheye).

Enter your license, then an admin password, to finish the setup. Note that this password is for the 'built-in' Fisheye admin user. You can log in as this user, if necessary, by clicking the Administration link in the page footer.

You can postpone setting up Jira integration until later if you wish; see Configuring Jira integration in the Setup Wizard.

8. Add repositories

Now you can tell Fisheye about any existing repositories you have. Please read Starting to use Fisheye for the details.

Fisheye will perform an initial index of your repositories, during which it accesses, indexes and organizes a view of your repositories (including all historical items) back to the earliest commits. If you are evaluating Fisheye, we suggest that you index a single project, so you can use Fisheye as soon as possible. If you choose to index your entire repository, be aware that this can take a long time (possibly days) for massive or complex repositories and can be more complex to set up (especially for Subversion). The basic process is slightly different for each SCM type.

9. Add users and groups

You will want to set up your users and groups in Fisheye. You can add users directly to Fisheye, or connect to an external user directory. Please read Starting to use Fisheye for an introduction.

10. Set up your mail server

Configure the Fisheye email server so that users can get notifications from Fisheye. See Configuring SMTP.

11. Connect to an external database (recommended)

If you intend to use this Fisheye installation in a production environment, it is highly recommended that you use one of the supported external databases. See Migrating to an external database.

If you are evaluating Fisheye, or don't wish to do this now, Fisheye will happily use its embedded HSQL database, and you can easily migrate later.  

12. Stop Fisheye (optional)

In a terminal, change directory to <FishEye install directory> and run this:

bin/stop.sh

13. Tuning Fisheye performance

To get the best performance from your new Fisheye installation, please consult Tuning Fisheye performance.

Last modified on Dec 13, 2018

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.