Installing the Java Service Wrapper

To install the Java Service Wrapper on Windows:

1. Download wrapper.zip from here .
2. Unzip the wrapper zip file into your <Crucible home directory> (that is, the directory into which Crucible was originally installed). Note, the resulting folder structure should be similar to <Crucible home directory>\wrapper or <Crucible home directory>\wrapper\bin, etc and NOT <Crucible home directory>\wrapper\wrapper or <Crucible home directory>\wrapper\wrapper\bin. The location of the wrapper directory is important.

3. Tell the wrapper where to find the Java JDK by editing the <Crucible home directory>\wrapper\conf\wrapper.conf file, replacing this:

   # Java Application
   wrapper.java.command=java

   with the following, and comment out the option you don't wish to use:

   # Java Application
    
   # Option 1: If you have JAVA_HOME defined in your Windows system environment variables, then you can use:
   wrapper.java.command=%JAVA_HOME%/bin/java 
    
   # Option 2: If you have multiple JDKs installed, and you don't want to use a Windows environment variable to specify which one to use, provide the absolute path to where the JDK is installed (e.g. C:/Java/jdk1.7.0_05/bin/java):
   wrapper.java.command=C:/<path to Java location>/bin/java
   

   To get confirmation in the wrapper log that the wrapper is using the correct Java JDK, add the following lines to the wrapper.conf file:

   # Tell the Wrapper to log the full generated Java command line.
   wrapper.java.command.loglevel=INF

   You can find the logs at <Crucible home directory>\var\log\wrapper.log.

    

4. Set the FISHEYE_INST environment variable (and other Crucible-specific environment variables) in the <Crucible home directory>\wrapper\conf\wrapper.conf file, following the instructions below.
5. Install Crucible as a service as follows:
   
   1. Open an Administrator command prompt by searching for 'Command prompt' in the Windows Start menu, right-clicking on Command Prompt and then choosing Run as administrator.
   2. Change directory to <Crucible home directory>\wrapper\bin and run Fisheye-Install-NTService.bat. If you run into any problems starting the wrapper, you'll find its logs in <Crucible home directory>\var\log\wrapper.log.
6. Start the Crucible service (which has the name 'Fisheye') from the Windows Control Panel; you can search in the Start menu for 'services', and in the list of services, right-click on the 'Fisheye' item and choose Start. You can also stop the Crucible service in this way.

Please note that:

• If you make changes to the wrapper.conf file, having already started the service, you need to stop and then restart the service for it to make use of the changed configuration.
• If in future you move the Crucible home directory, you will need to uninstall (using Fisheye-Uninstall-NTService.bat) and then reinstall the Crucible service.

Setting Crucible environment variables for Windows Services

Please note, that if you run Crucible as a Windows service, any Crucible-specific environment variables must be set in your <Crucible home directory>\wrapper\conf\wrapper.conf file.

If you run into any problems starting the wrapper, you'll find its logs in <Crucible home directory>\var\log\wrapper.log.

If there are other Java parameters you wish to add, then you will need to add them under the additional parameters section, e.g.

# JDK Additional Parameters for jmx
wrapper.java.additional.4=-Dcom.sun.management.jmxremote
wrapper.java.additional.5=-Dcom.sun.management.jmxremote.port=4242
wrapper.java.additional.6=-Dcom.sun.management.jmxremote.authenticate=false
wrapper.java.additional.7=-Dcom.sun.management.jmxremote.ssl=false
wrapper.java.additional.8=-Dcom.sun.management.jmxremote.authenticate=false
wrapper.java.additional.9=-Dcom.sun.management.jmxremote.password.file=./wrapper/jmxremote.password
wrapper.java.additional.10=-Dwrapper.mbean.name="wrapper:type=Java Service Wrapper Control"

To add the FISHEYE_INST environment variable, the Java MaxPermSize parameter, or the -Xrs options, use the following:

wrapper.java.additional.11=-Dfisheye.inst="c:/path/to/FISHEYE_INST"
wrapper.java.additional.12=-XX:MaxPermSize=128m
wrapper.java.additional.13=-Xrs

Note that the the -Xrs options should be used when running Crucible as a service under Windows to prevent the JVM closing when an interactive user logs out.

Your memory settings can also be found in this file:

# Initial Java Heap Size (in MB)
wrapper.java.initmemory=256

# Maximum Java Heap Size (in MB)
wrapper.java.maxmemory=1024

Increase these values if you have a large repository or expect to use more memory (init of 256, and a max of 1024 are the default values).

In Fisheye/Crucible 1.6.4 and higher, you can check the JVM input arguments by clicking System info, under 'System Settings' in the admin area.

Troubleshooting

Extracting files from wrapper.zip

Some customers have reported trouble running the wrapper. These can be avoided by:

• Uncompressing wrapper.zip with Winzip or WinRar rather than using the Extract All command in the Windows right-click contextual menu.
• If the wrapper.zip filename appears green instead of black in Windows Explorer, decrypt it, prior to unzipping its contents, by right-clicking on the file, choose Properties, click the Advanced button, then clear the Encrypt contents to secure data checkbox.

Warning when using 64-bit Java JDK

When using a 64-bit Java JDK with the wrapper obtained via the link in the install instructions above, you may see the following in the wrapper.log file:

WARNING - Unable to load the Wrapper's native library 'wrapper.dll'. The file is located on the path at the following location but could not be loaded: C:\installs\service\fisheye28\wrapper\lib\wrapper.dll.

Please verify that the file is readable by the current user and that the file has not been corrupted in any way. System signals will not be handled correctly.

This is caused by using a 64-bit JDK (even on a 64-bit machine). Changing to a 32-bit version of the JDK will prevent this warning. Community Edition versions of the 64-bit Windows Java Service Wrapper are not currently available.

Wrapper configuration and "-server" parameter

Please note that the wrapper configuration provided above uses the -server parameter to enable the Java HotSpot(TM) Server VM. This feature is only available if you use the JDK. If you use the JRE you will likely get the following error in your logs:

INFO | jvm 1 | 2010/12/20 18:19:28 | Error: missing `server' JVM at `C:\Program Files\Java\jre6\bin\server\jvm.dll'.

A common issue is that customers remove the -server parameter from the wrapper.conf file. Please note that if you do this, the wrapper script will ignore any of the following JVM parameters in the file unless you change the sequence to be in order, starting from wrapper.java.additional.1. This is an issue with the Wrapper application.

In this situation it's best to install and run Fisheye/Crucible with the JDK to get all the advantages of the -server functionality. You also need to force the wrapper to use the JDK by specifying the path to the Java JDK in the wrapper.conf file, as described in the installation instructions above.