This page last changed on Jun 22, 2011 by smaddox.


There will be much flapping of wings and breathing of fire. You are embarking on stage 4 of the Atlassian Dragon Quest.

In this stage, you will install FishEye for breathtaking overviews of your source code repository and Crucible for piercingly insightful code reviews. Prepare to be blown away by FishEye/Crucible's integration with JIRA and Bamboo.

Time estimate: This stage will take approximately 30 minutes.

On this page:

Step 1. Create your FishEye Database in PostgreSQL

Now you will create a database where FishEye will store its data, and the user that FishEye will use to connect to the database. Crucible will use this database as well. We are assuming that you have already created your PostgreSQL database server in Dragons Stage 1.

We are using pgAdmin III, the administration user interface supplied with PostgreSQL. If you used the one-click installer in Dragons Stage 1, pgAdmin III will be already installed on your computer.

  1. Start pgAdmin III.
  2. Add a new login role called 'fishuser':
    • Right-click 'Login Roles' and select 'New Login Role'.
    • Enter the role 'Role name': fishuser.
    • Enter a suitable 'Password' and enter it again to confirm it.
    • Click the 'Role privileges' tab.
    • Select 'Can create database objects'.
    • Select 'Can create roles'.
    • Click 'OK' to create the user.
  3. Add a new database called 'fisheye':
    • Right-click 'Databases' and select 'New Database'.
    • Enter the database 'Name': fisheye.
    • Select the 'Owner': fishuser.
    • Click 'OK' to create the database.

Alternatively, If you are on UNIX and do not have pgAdmin III, you can use the command line interface instead. Assuming that you are using the default installation directory of /opt/PostgreSQL/8.3/bin/, enter the following commands:

sudo -s -H -u postgres
# Create the FishEye user:
/opt/PostgreSQL/8.4/bin/createuser -S -d -r -P -E fishuser
# Create the FishEye database:
/opt/PostgreSQL/8.4/bin/createdb --owner fishuser --encoding utf8 fisheye
exit

Screenshot 1 (click to enlarge): FishEye/Crucible database and user in PostgreSQL

Problems? Please raise a support ticket for the product you're stuck on, see answers from the community, or search the forum of past dragon slayers.
Victory? Please continue.

Step 2. Install FishEye and Crucible

Requirements: FishEye/Crucible 2.6.

For Windows: (click to expand)
  1. Go to the Atlassian download centre.
  2. Download the 'FishEye 2.6' zip archive. This archive includes Crucible 2.6 as well.
    Please use the FishEye version specified in this documentation. If the download centre shows a FishEye version later than 2.6, click 'downloads archive' and get FishEye 2.6.
    Why? We have tested the integration suite with this version. There is a chance that you will have problems integrating the other applications if you use a different version.
  3. Unpack the zip archive into a directory of your choice, avoiding spaces in the directory name. For example: c:\fisheyecrucible. We will now refer to this location as the FishEye/Crucible installation directory.
  4. Now you will create another directory where FishEye/Crucible will store local data, separate from the installation directory:
    • Create the new directory, e.g. C:\data\fisheyecrucible.
    • Create an environment variable called 'FISHEYE_INST' and point it to your new data directory. (Open your Windows 'Control Panel'. Click 'System' to open the 'System Properties'. Click the 'Advanced' tab. Click 'Environment Variables'. Add a new 'System variable' with the name 'FISHEYE_INST' and a value of your new data directory's location, such as C:\data\fisheyecrucible.)
      Note: Ignore the fact that this environment variable is called 'INST'. It has nothing to do with the installation directory. This environment variable points to the data directory, but it must still have the name specified above.
    • Copy the config.xml file from the root of your FishEye/Crucible installation directory to the root of your new data directory.
  5. Because FishEye/Crucible will be running on the same machine as JIRA (already installed), you need to ensure that the URL paths are different for FishEye/Crucible and JIRA. Change the default FishEye/Crucible path as follows:
    • Edit the config.xml in your FishEye/Crucible data directory.
    • Add the context attribute to the web-server element:
      <web-server context="/fisheye">
  6. Now you will make your PostgreSQL driver available to FishEye/Crucible:
    • Create a \lib directory as a sub-directory of your new data directory
    • Copy the PostgreSQL JDBC driver JAR (downloaded in Dragons Stage 1) to the new \lib directory.
  7. Start FishEye/Crucible from the command line by running bin\run.bat from your FishEye/Crucible installation directory.
    • Wait a few minutes for the server to launch. This message will appear on the command line once ready:
      'INFO - Server started on :8060 (http) (control port on your-server-IP-address:8059)'.
For Linux: (click to expand)
  1. Go to the Atlassian download centre.
  2. Download the 'FishEye 2.6' zip archive. This archive includes Crucible 2.6 as well.
    Please use the FishEye version specified in this documentation. If the download centre shows a FishEye version later than 2.6, click 'downloads archive' and get FishEye 2.6.
    Why? We have tested the integration suite with this version. There is a chance that you will have problems integrating the other applications if you use a different version.
  3. Unpack the zip archive into a directory of your choice, avoiding spaces in the directory name. For example: /opt/fecru-x.x.x. We will now refer to this location as the FishEye/Crucible installation directory.
  4. Now you will create another directory where FishEye/Crucible will store local data, separate from the installation directory:
    • Create the new data directory, e.g. /opt/fisheyecrucible.
    • Create an environment variable called 'FISHEYE_INST' and point it to your new data directory.
      Note: Ignore the fact that this environment variable is called 'INST'. It has nothing to do with the installation directory. This environment variable points to the data directory, but it must still have the name specified above.
    • Copy the config.xml file from the root of your FishEye installation directory to the root of your new data directory.
  5. Because FishEye/Crucible will be running on the same machine as JIRA (already installed), you need to ensure that the URL paths are different for FishEye/Crucible and JIRA. Change the default FishEye/Crucible path as follows:
    • Edit the config.xml in your FishEye/Crucible data directory.
    • Add the context attribute to the web-server element:
      <web-server context="/fisheye">
  6. Now you will make your PostgreSQL driver available to FishEye/Crucible:
    • Create a /lib directory as a sub-directory of your new data directory.
    • Copy the PostgreSQL JDBC driver JAR (downloaded in Dragons Stage 1) to the new /lib directory.
  7. Start FishEye/Crucible from the command line by running ./bin/run.sh from your FishEye/Crucible installation directory.
    • Wait a few minutes for the server to launch. This message will appear on the command line once ready:
      'INFO - Server started on :8060 (http) (control port on your-server-IP-address:8059)'.

Problems? Please raise a support ticket for the product you're stuck on, see answers from the community, or search the forum of past dragon slayers.
Victory? Please continue.

Step 3. Set Up FishEye and Crucible

In this step you will do the initial setup of your FishEye/Crucible site. As part of this process, you will connect FishEye and Crucible to JIRA, so that you can manage all your users via JIRA and share information between JIRA and FishEye/Crucible.

  1. To access FishEye/Crucible, go to your web browser and type this address: http://localhost:8060/fisheye. Alternatively, type the host name or IP address instead of localhost.
  2. The FishEye/Crucible setup wizard will start.
    • If you already have a license key, click 'Enter existing license'. Enter your FishEye license into the 'FishEye License Key' field and your Crucible license into the 'Crucible License Key' field.
    • If you do not have a license key, click 'Obtain evaluation license' and follow the instructions on screen. If prompted, ensure that you choose to include Crucible as part of this evaluation.
  3. The 'Connect to JIRA' step will appear. Enter the following information:
    • JIRA Base URL – Enter the web address of your JIRA server, e.g. http://www.foobar.com:8080.
    • Admin Username: charlie.
      This is Charlie's username in JIRA.
    • Admin Password – Enter Charlie's password for JIRA.
  4. Leave the other fields (the 'advanced options') at their default values and click the 'Connect to JIRA' button.
  5. The 'Set administrator password' screen will appear. Enter an administration password and then enter it again to confirm it.
    This is the password you can use to access your FishEye/Crucible administration screens. Charlie will also have permission to access the administration screens.
  6. Click 'Next'.
  7. Click 'Add repository' to exit the wizard.
  8. Log in to FishEye/Crucible when prompted.
    You can use the administration password that you defined in the previous step, or you can use Charlie's login. We recommend that you log in as Charlie:
    1. Click 'Log In' in the top menu bar.
    2. Enter the username 'charlie' and Charlie's password in JIRA.
    3. Click the dropdown arrow on the right of Charlie's name in the top menu bar, and select 'Administration'.
  9. Now you will connect FishEye/Crucible to your database. In the left-hand 'Admin' menu, click 'Database' under 'Systems Settings'.
  10. Click 'Edit' and enter the following details:
    • Type – Select 'PostgreSQL'.
    • Driver Location – Select 'User Supplied - FISHEYE_INST/lib'.
    • URL: jdbc:postgresql://localhost:5432/fisheye – Note that this value is different from the default value.
    • User Name: fishuser – This is the user you created in step 1 (above).
    • Password – Enter the password you defined in step 1 (above).
  11. Click 'Test Connection' to verify that FishEye/Crucible can log in to the database.
    If the test fails:
    • Verify that you have the PostgreSQL JDBC driver JAR file in the FishEye data directory (see step 2 above). Note that this is not your installation directory.
    • Also ensure that the database user can log in to the database from the machine that FishEye/Crucible is running on and that all the required privileges are present.
    • Hint: If you have a virus checker running, there may be a delay in the driver's availability after you have placed the driver JAR into the directory, while the virus checker scans the file. Wait a while and try again.
  12. Click 'Save & Migrate'.

Screenshot 2 (click to enlarge): FishEye/Crucible database migration successful

Full details are in the FishEye documentation.

Problems? Please raise a support ticket for the product you're stuck on, see answers from the community, or search the forum of past dragon slayers.
Victory? Please continue.

Step 5. Connect FishEye to Bitbucket

For this integration exercise we provide a Bitbucket repository that you can connect to your FishEye 'Dragons' repository. Bitbucket is a code hosting site for the Mercurial distributed version control system (DVCS). We recommend this repository because:

  • We have committed a code change with a JIRA issue key in the commit message, to match a JIRA issue you created earlier. This will allow you to see the JIRA and FishEye integration immediately, without having to do your own commit.
  • The sample repository is small, so that FishEye's initial repository indexing process will be fast.

FishEye supports Mercurial, Subversion and a number of other repository types. When you start using FishEye outside this integration exercise, you will need to create another FishEye repository and connect it to your source repository as described in the FishEye documentation.

For this integration exercise, follow the steps below to install Mercurial and then connect to our sample repository.

  1. Get Mercurial and Python. Make sure that you get Mercurial 1.5 or later.
    • If you are on Windows you can download and install TortoiseHg. This bundles Python and Mercurial.)
    • Note: For some UNIX distributions, the default download will include Mercurial 1.4.3. You will need 1.5 or later.
  2. Add or edit your Mercurial config file at C:\Documents and Settings\MY_NAME\mercurial.ini (Windows XP) or C:\MY_NAME\mercurial.ini (Windows 7) or ~/.hgrc (UNIX). The file should contain your preferred editor and your username. If you do not already have a username, you can use atlassian_dragons:
    [ui]
    ; editor used to enter commit logs, etc.  Most text editors will work.
    editor = notepad
    username = atlassian_dragons
    
  3. Go to your FishEye administration screen in your browser.
  4. In the left-hand 'Admin' menu, click 'Repositories' under Repository Settings.
  5. Click the 'Add' button. The first screen of the 'New Repository' wizard will appear.
  6. Enter the following information:
    • Repository Type: Mercurial.
    • Name: Dragons.
    • Description: Dragons repository.
  7. Click 'Next' and enter the following information:
  8. Click 'Next' and enter the following information:
    • Store Diff Info – Select this checkbox.
    • Enable Repository After Adding – Select this checkbox.
  9. Click 'Test Connection' to verify that Bitbucket is properly connected to FishEye. Click 'Close'.
  10. Click 'Add'. The 'Repositories' page will display the 'Dragons' repository.
  11. Click the 'Source' tab at the top of the screen.
  12. Click the star symbol next to the 'Dragons' repository to select it as a favourite.
  13. Click the FishEye logo at top left of the screen to return to the FishEye dashboard. You should be able to see the activity stream showing recent commit messages for the repository.
    If you do not see any activity, please wait a while for FishEye to finish scanning (indexing) the repository. With our sample repository, this should only take a few minutes.

Screenshot 3 (click to enlarge): FishEye dashboard with activity stream

Full details are in the FishEye documentation. You can learn about Bitbucket and Mercurial in the Bitbucket documentation.

Problems? Please raise a support ticket for the product you're stuck on, see answers from the community, or search the forum of past dragon slayers.
Victory? Please continue.

Victory!

You can now see your source in FishEye. Go to the FishEye dashboard, click the 'Source' tab and click 'Dragons' to browse the contents of your new 'Dragons' repository.

If your repository is large, FishEye may take a while to index all your files. If the index scanning is still underway, you will see a message at the top of the screen saying 'NOTE: The repository is being scanned, some statistics may not be up to date. ...

Want an RSS feed of your repository activity? Go to the 'Activity' tab on the 'Source' view. Click 'Tools' then 'RSS Feed'. You can get an RSS feed on the dashboard too.

Click the changeset number (0:922fd9308885) in the activity stream to see FishEye's view of your source code.

Screenshot 4 (click to enlarge): FishEye source repository viewer

Problems? Please raise a support ticket for the product you're stuck on, see answers from the community, or search the forum of past dragon slayers.
Victory? Please continue.

Grab your Shield and Move to the Next Stage

Document generated by Confluence on Jun 22, 2011 21:05