This documentation relates to an earlier version of FishEye.
View

Unknown macro: {spacejump}

or visit the current documentation home.

This guide describes the advanced FishEye installation options.

Evaluating FishEye for the first time? See the FishEye 101 page.

  1. Download the FishEye zip file and extract it to a folder on your local computer.
    (warning) Folder names in the path to your FishEye executable should not have spaces in them.
    (info) The directory where you have extracted FishEye is referred as /FISHEYE_HOME/ below.
  2. Ensure you have installed an appropriate Java runtime - see Supported Platforms.
  3. Ensure that java is in the PATH, or that the JAVA_HOME environment variable is set.
  4. Go to /FISHEYE_HOME/ and run bin/start.sh if you are on Linux/MacOS, or bin\start.bat on Windows.
  5. Wait for a few seconds for FishEye to start.
  6. Open your browser at http://localhost:8060/ (or type http://hostname:8060/, where hostname is the name of the machine where you extracted FishEye).
  7. Enter your license, then the admin password to finish the setup.
  8. If you intend to use FishEye with Subversion, please ensure you read Supported Platforms, Subversion client setup, and granting permission to FishEye to scan your repository.
  9. If you intend to use FishEye with Perforce, please ensure you read Perforce client setup.

Read-only access for FishEye

We recommend that you run FishEye as a user that has only read access to your repository.

If you're running Fisheye on Windows you might want to install it as a service so that Fisheye start-up automatically during start-up

Number of files

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

Detailed Installation Guide

See the guidelines on Running FishEye for the First Time.

FishEye Folder Layout

FISHEYE_HOME (Default)

By default, FishEye will run self-contained within the /FISHEYE_HOME/ directory. The FishEye directory layout looks like this:

/FISHEYE_HOME/config.xml

Configuration file.

/FISHEYE_HOME/var/

Directory under which FishEye stores its data.

/FISHEYE_HOME/var/data/

Persistent information.

/FISHEYE_HOME/var/cache/

Caches and indexes.

/FISHEYE_HOME/var/log/

Log files.

/FISHEYE_HOME/var/tmp/

Temporary files.

/FISHEYE_HOME/cache/

Caches and indexes. (in addition to FISHEYE_HOME/var/cache)

/FISHEYE_HOME/bin/

Scripts for controling FishEye.

/FISHEYE_HOME/lib/

FishEye's dependent libraries.

/FISHEYE_HOME/ ...

Remainder omitted for brevity.

However, this self-contained layout results in tedious copying of files each time you upgrade FishEye. Also, if you want to run multiple instances of FishEye, you need multiple /FISHEYE_HOME/ installations. These two issues can be avoided by setting a FISHEYE_INST ('FishEye Instance') location.

FISHEYE_INST (Optional)

FISHEYE_INST is a location where your repository data is stored, separate from the installation location of the FishEye application. This may be necessary for practical or administrative reasons.

(info) Use of a separate FISHEYE_INST location is recommended for production installations of FishEye.

You must copy your config.xml to the new FISHEYE_INST

Once you have declared your FISHEYE_INST, you will need to copy your FISHEYE_HOME/config.xml file to your FISHEYE_INST/ directory.

When the FISHEYE_INST environment variable is set, FishEye's directory layout becomes:

$FISHEYE_INST/config.xml

 

$FISHEYE_INST/var/

All permanent and most temporary data is found under $FISHEYE_INST/var/

$FISHEYE_INST/cache/

Caches and indexes are found under $FISHEYE_INST/var/ (in addition to $FISHEYE_INST/var/cache)

$FISHEYE_INST/lib/

Site-specific Java libraries (.jars) that FishEye should load on startup. (Do not copy the dependent /FISHEYE_HOME/lib/ files into here.)

$FISHEYE_INST/syntax/

Site-specific syntax highlighting definitions.

$FISHEYE_INST/system.properties

Used for setting system properties within the FishEye JVM, which may sometimes be useful for support purposes.(Note: the other way to set properties is via FISHEYE_OPTS, e.g.: export FISHEYE_OPTS=-Dpropname=value )

/FISHEYE_HOME/lib/

FishEye's dependent libraries.

/FISHEYE_HOME/syntax/

FishEye bundled highlighting definitions.

/FISHEYE_HOME/bin/

 

/FISHEYE_HOME/ ...

Remaining files are found under /FISHEYE_HOME/.

The rest of this Installation Guide refers to $FISHEYE_INST/, but if you have not set FISHEYE_INST then it defaults to /FISHEYE_HOME/ (the directory where you extracted FishEye).

18 Comments

  1. CesarCnf

    Jul 19, 2010

    If you follow the dragons quest, at the Stage 5 - step 2 and compares with this "Installing FishEye" document, i supose that, like the all other application suite, the most suitable indication by the install folder (/opt/fecru-x.x.x) and home folder (/usr/local/fisheye) its from the first, and will be a better policy mantain the same layout than the other services/tools both for enviroment vars and the directories. Bye :D

  2. Doug Ross

    Dec 10, 2010

    The placeholder (variable) names used in the documentation are confusing. FISHEYE_INST makes me think of where the install files live. But really it means "instance." This has confused my team more than once.

    One way to clarify might be to use slightly more complete, descriptive variable names: 

    FISHEYE_INSTALL=/apps/fecru/
    FISHEYE_INSTANCE=/apps/fecru/data/instance1/
    or
    FISHEYE_INSTALL=/apps/fecru/
    FISHEYE_DATA=/apps/fectru/data/
    or
    FISHEYE_HOME=/apps/fecru/
    FISHEYE_DATA=/apps/fecru/data

    1. Anonymous

      Mar 08, 2011

      agreed

    2. Anonymous

      May 25, 2011

      agreed.

      Also this line is not clear

      "When the FISHEYE_INST environment variable is set, FishEye's directory layout becomes:"

      HOW does it become like this?

      The whole setup for FishEye on Linux is a bit like trial-and-error.

      I could also not find instructions regarding which permissions the fisheye user account is required to have in the system.. (or am I supposed to have it run as root??)

      The Confluence guys did a nice job on this topic here: http://confluence.atlassian.com/display/JIRA043/Installing+JIRA+Standalone+on+Unix+or+Linux#InstallingJIRAStandaloneonUnixorLinux-3.StartJIRA

    3. Anonymous

      May 30, 2012

      Reading through the install documentation, I have to agree with you completely on this one.  The current design doesnt have any Atlassian 'zing' to it.  With so many products, why has Atlassian let this one become the exception to the rule?

  3. Anonymous

    Mar 03, 2011

    How do i verify integrity of the downloaded zip? Thanks.

  4. Anonymous

    May 13, 2011

    you can check the contents of the file  with the command "unzip -l"

  5. Anonymous

    May 18, 2011

    For JIRA and confluence I can set the data directory in a config file (a .properties file). Is there a way to do this for fisheye? I'd rather not maintain separate environment variables, but prefer a standard file based approach between systems.

    1. Anonymous

      Aug 16, 2011

      I'll answer a few questions here just form experience:

      1. NO, never run any web application under root, that is asking for trouble!
        Run fisheye under a dedicated, non-priveledged user will rwx access on the fisheye install and data directories 
      2. There is no properties file, but I just edited fisheyectl.sh to export the location prior to startup: 
        \#\!/bin/bash
export FISHEYE_INST=/opt/lforge/atlassian_data/fisheye_home
bin/run.sh &

      1. Anonymous

        Oct 05, 2011

        Hi there,

        Thanks for the tip.

        I found on Mac OS X that despite the fact that I have FISHEYE_INST variable set correctly in ~/.profile

        (echo $FISHEYE_INST - displays my handcrafted path correctly)

        That the SYSINFO tab in Crucible still stated that my INST location was the same as the HOME location.

         

        In bin/fisheyectl.sh is the following line;

        if [ -z "$FISHEYE_INST" ] ; then
          FISHEYE_INST=$FISHEYE_HOME
        fi

        I assume, that for some reason that this test for the INST variable does not work on Mac OS X.

        I changed it to;

        if [ -z "$FISHEYE_INST" ] ; then
          FISHEYE_INST=/my/correct/location/
        fi

        And Crucible has started correctly - with my existing repo and commits / reviews.

         Thanks - Gavin.

  6. Anonymous

    Nov 19, 2011

    I am installing almost all of the atlassian products this evening. The instructions for Fisheye and Crucible are the least obvious. It seems I have to redo my installation because the instructions for production are given at the end.

  7. Anonymous

    Dec 25, 2011

    Agree with others.

     

    This document is not written with production systems in mind. Why document things at the end. Most users installing Fisheye are doing it for production and its a waste of time to go through this multiple times.

    Not to mention Syncing all this up with Crowd.

  8. Anonymous

    Feb 16, 2012

    These instructions are very unclear and need a technical writer to redo them completely.  I am jumping all over the place trying to find what I need, and it's trial and error.  For instance, it doesn't appear I can start with a MySQL database from the beginning – I have to migrate to it.  And finding the doc link to external DB setup was not easy – I had to get it through the system requirements page.  And are you supposed to copy the config.xml before or after you've configured your FISHEY_INST env variable.  These instructions should be far more step by step.  Too many assumptions are made.  Now for JIRA integration, oh joy.

  9. Anonymous

    Feb 17, 2012

    I agree with many of the statements made here.  The fisheye install instructions are very poorly written. In trying to understand on how to install for a production environment, you end up all over the place and by the time you have performed part of the installation, your so lost your not sure what you have or have not installed and what you still need to do/configure.  If the document is going to be 50 links atleast make it like code w/ if then sections.  For ex, method of service: If running as windows service or running as windows application, etc.....

  10. David Chung

    Mar 26, 2012

    One thing to note is that /FISHEYE_HOME/var/ can grow very large. I was used to confluence and JIRA separating its /var and binaries and neglected that /FISHEYE_HOME/ combined the two. Came in over a weekend of indexing my repositories to find that my root file system was out of space...

  11. Anonymous

    Jul 19, 2012

    I'm really sorry that I have to say this, but the quality of this documentation is rather insulting for someone who paid money for a product.

    The recommended configuration (separate paths for HOME and INST) is not explained at all, just a few brief statements were given (the directory structure "becomes" different - great! How about telling me what I need to do to make it "become" like that? Any why do I need to duplicate my config.xml by copying it? Is this an error in the documentation or is it really intentional and necessary to compensate poor application design?).

    This document does not even bother to mention that a external database is recommended for production use. Why should it? There's the most amazing "Dragons - Stage 5" Document available that will tell me. Of course the intuitive name makes it most easy to find that document. But fortunately it's not linked from this page, so a new customer will certainly use the search function to check if he should use an external database. On a short side note: The adventure-like style of writing is really a pleasure after you have already wasted your time on following the instructions here or on some other random pages linked here or elsewhere.

    One of them would be the "Detailed Installation Guide"-section of this document which just asks me to read "Running FishEye for the First Time" which is actually a link to "Configuring Fisheye" (semantics?). In the end I got another useless piece of documentation (except for the mentioning of port 1059 to be used there's basically no new information) which is so not-detailed that it even skips mentioning the (recommended?) use of FISHEYE_INST. Of course there's also no remark about HSQL being unreliable and that an external database should be used for production installations. I guess new customers just happen to know this fact from their daily newspaper.

    So, after reading all the documents (another hour wasted for nothing) the conclusion is that rather than following this useless documentation here (or in the equally useless "Configuring Fisheye" document), one should just read Step 3 in the "Dragons - Stage5" document (well hidden by a "Click to expand"-Line) because there a simple best-practice-like approach is documented. Thank you so much.

    By now the only thing which is unclear is the need to define a (system wide) environment variable for the FishEye paths. Why can't it simply be set in the start.sh script? Would that be too easy? Too self-contained? Or is there actually a reason for it? Maybe I should search for "castle" or maybe "elves" to find the corresponding documentation? After all "dragon" brought up the right answer to my earlier question. Is this funny? No.

     

    I can absolutely understand that writing technical documents might not be the most fulfilling, entertaining and joyful thing to do. But is that a reason to do it this poorly? Whoever wrote this document was being paid for it, right? Actually paid by people who now pay money for your product. So please have the decency to do a proper job, especially as your laziness is straining other people. This is not open source, this is not a community product, I don't have a way to fix the documentation myself (rather than wasting time on writing this comment!). Thank you.

     

    Maybe you can understand that doing an administrators job is as well something which is not entertaining and which might also not be a joyful thing to do (mostly because of bugs and poor documentation). It's hard work, usually not paid well, and hardly fun, but it needs to be done diligently and efficiently. Please don't make it more difficult than it already is. Thank you.

     

    So... how hard can it be to provide a guide which explains all necessary steps to perform a production installation according to best practices? You almost managed to do so in the "Guide to Installing an Atlassian Integrated Suite" (which contains the silly "dragon tale").

    Having your technical writers do a proper job on this product would help so many people save time, money and frustration.

    Maybe the product manager who made the decision to keep the documentation of this product at the current level can reconsider investing the few hours of effort to rework the documentation. Judging from the comments on this page I might not be the only person who would really appreciate this.

     

    Thank you very much for reading all of this.

    1. paulwatson

      Jul 24, 2012

      Thank you very much for writing all of that! And thanks for caring enough to spend the time on such a detailed summary of the problems with these pages.

      Please be assured that we have been aware of this for a while ( FE-4121 - Getting issue details... STATUS ) and have been working to improve the whole set of install and config docs for the FishEye 2.8 release, due in a few weeks. The core page will follow the same approach as Installing Stash on Windows, the intention being to include all necessary steps and to minimise the number of links out to other pages. I'd appreciate your comments on that approach...

      regards, Paul

      1. Anonymous

        Aug 03, 2012

        Dear Paul Watson,

        thank you for your response.

        What I miss most is:

        • Clear indication of best practices for production setups (e.g. "Install to /example/atlassian", "Always use external database", "Use HTTPS", "Configure email notifications like this..", "install as user x for product x and y but as user z for product z", etc.) - this should consider that most companies store sensible data in their Wiki/Tickets/Source Code, etc. so Authentication, Encryption, etc. is usually desired or mandatory.
        • Provide explanation for basic security measures like:
          • Install as non-privileged user. Maybe the new installer does this? last time i tried to run one as root in update-mode it messed up my local filesystem permissions and put unresolved uids there, had tons of files writable/readable who don't need any access there, etc. - that cured my desire to test this again...
            • Filesystem permissions don't seem to be of interest in general in your release management - why does my webserver need to be able to write to / alter most of the application's files anyway? If I really want that I can install Wordpress...
          • Use https. It's already recommended to use mod_proxy with Apache - adding https takes additional <5 minutes on most standard distributions (Ubuntu: "a2ensite default-ssl && a2enmod ssl" - done?). If you can't live with a snakeoil-cert you know what to do to resolve that anyway so no need to cover that IMO.
          • Binding tomcat services to localhost once they are not needed to be accessed from outside anymore. Your application links do work over HTTPS/Apache mod_proxy when configured correctly! No need to have tomcat bind to 0.0.0.0 and have JRA-27719 et. al. compromise my system. I don't think that's common knowledge for everyone.
          • Explain how to use authentication integrated in Apache (AuthType *) to access all Atlassian products. This will secure the system against any Atlassian security issues (JRA-27719), while at the same time allowing to implement fancy stuff like Kerberos SSO, etc. which might be really nice for larger setups?
          • Explain how to secure application links. It's not that much effort to implement if you know that you need to add the ca of your https-cert to your standalone-installations' keystores for application links to work and that you will need to add some "Allow from <server-ip>" statements in your Apache config as some of Atlassian components don't seem to support http(s)-based authentication.
        • Focus on Robustness
          • Startup / Shutdownscripts are not reliable currently (don't provide proper error message / exit code if there's a problem, "stop" does not terminates the process reliably, ...). The reworked Stash-Documentation does not cover that for Mac/Linux as far as I could see.
          • Minor: Things like logrotate are not covered at all (yes, disk space is cheap by now, but backup space isn't - so it's more than just "nice to have").
          • Minor: Monitoring is not covered at all currently (I'd like to check if my JIRA is running properly by using Nagios - e.g. which error-log files will grow in case of problems? What are the patterns to look for? Is there a status-page I can scan for "component x failed" / "update y pending" messages? etc.)
        • Clear explanation on how the various tools (Jira, Confluence, Fisheye, Crucible, ..) interact on technical level. When is an application link needed? What are bandwidth / latency requirements? Can I put it through a proxy? Are there firewall-considerations to be aware of? etc.
        • Clear naming for variables / internal terms ("FISHEYE_INST" is an excellent bad example).
        • Clear naming in example-configurations ("point to http://yourserver.com/jira" is way more informative than "point to your JIRA server")
        • Clarify *technical* benefit of integration with other products (e.g. why do I really need Crowd when I can basically do SSO using LDAP and Kerberos?) - admins rarely care about marketing foo - and the product has ben bought already anyway and your product will run better when the person who set it up understood what he's doing and why.

        IMO It would also be nice if you could provide a separate guide for an evaluation installation. The scope is completely different when evaluating: There's no need for security, maintainability, backup, etc. - while all those things are really important for a production setup. So distinguishing here might make your new / potential customers happy as they got a way to do a "one click setup" easily without technical skill (is there a vmware image actually?), and after they have decided to use/buy the product, their admin will be happy to have a clear best practice guide he can follow.

        Also I think it's a really bad ida to cover Linux and Mac installations in the same way. I've seen very few people on Mac careing about (and understanding) security while most servers in hostile environments run Linux. On a side note: Finding a .DS_Store in an offical "released for linux" file (forgot which product that was..) is not really leaving a good impression. Regarding Stash: If Mac OS X is supported for evaluation use only - why make the MAC paths the default in your documentation?

        As it might be relevant for you to know the requirements for my primary use cases for Atlassian products - they are:

        • system must be accessible from anywhere reliably and in a secure way
        • access is restricted to a closed group of users (this must be ensured due to sensible data in the system)
        • development, issue tracking, management, etc. is done by various parties located in several locations worldwide so performance and ease of use are relevant

         

        I hope this feedback will help you to improve the documentation quality.

         

        Kind Regards



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.