Implementing the Handle Server on Windows using the Tanuki Service Wrapper

Introduction

This guide is based on the Tanuiki WrapperSimpleApp Integration modified to allow the DSpace handle server to be run as a Microsoft Windows service. Many thanks to Tanuki for allowing this guide to be posted.

More information on the Tanuki project along with the software required can be found at: http://wrapper.tanukisoftware.org/

This installation guide will refer to the path of the DSpace installation as dspace, the path of the DSpace source as dspace-src and the path of where the Tanuki software is extracted to as wrapper.

Registering for a Handle

1) The Handle server code is included with the DSpace code in

[dspace]/lib/handle.jar

. Note: The latest version of the handle.jar file is not included in the release due to licensing conditions changing between the provided version and later versions. It is recommended you read the new license conditions and decide whether you wish to update your installation's handle.jar. If you decide to update, you should replace the existing handle.jar in dspace/lib with the new version and rebuild your war files.
2) Firstly generate the

sitebndl.zip

by running the following command and completing the questions:

[dspace]/bin/dsrun net.handle.server.SimpleSetup [dspace]/handle-server

3) Register for your handle at http://hdl.handle.net/4263537/5014 (CNRI Handle.net). You will be required to fill in details about your organisation, pay a small annual fee and upload the sitebndl.zip which was generated in the previous step and can be located in

[dspace]\handle-server\sitebndl.zip

4) The registration process should take about one week. Once completed you should receive a handle which can be used to update DSpace.

Updating DSpace

1) Once you receive your handle, it will need to be updated in the dspace\dspace.cfg. Update the following line to your own handle code:

##### Handle settings ######
# CNRI Handle prefix
handle.prefix = 123456789

2) Once updated you will need to save the dspace.cfg file and restart Tomcat.
3) If you need to update the handle prefix on items created before the CNRI registration process you can run the

[dspace]/bin/update-handle-prefix

script. You may need to do this if you loaded items prior to CNRI registration (e.g. setting up a demonstration system prior to migrating it to production). The script takes the current and new prefix as parameters. For example:

[dspace]/bin/update-handle-prefix 123456789 1303

will change any handles currently assigned prefix 123456789 to prefix 1303, so for example handle 123456789/23 will be updated to 1303/23 in the database.

Updating the Handle-Server

1) Edit the resulting file config.dct found at

[dspace]/handle-server/config.dct

to include the following clause in the "server_config" clause:

"server_config" = {
"storage_type" = "CUSTOM"
"storage_class" = "org.dspace.handle.HandlePlugin"
"server_admins......

2) Update all references to YOUR_NAMING_AUTHORITY to your handle prefix. i.e.:

"300:0.NA/YOUR_NAMING_AUTHORITY"
"300:0.NA/1303"

Installing the Tanuki Service Wrapper

1) Download the Tanuki Java service wrapper and extract to wrapper

2) Copy the following file from

[wrapper]\bin

into the

[dspace]\bin

directory

[wrapper]\bin\Wrapper.exe

3) Copy the following files from

[wrapper]\src

into the

[dspace]\bin

directory

[wrapper]\src\bin\App.bat.in
[wrapper]\src\bin\InstallApp-NT.bat.in
[wrapper]\src\bin\UninstallApp-NT.bat.in

4) Rename the three batch files as below and ensure the .in extension is removed. Depending on how your file explorer is configured, you may not be able to see the extensions.

[dspace]\bin\App.bat.in -> [dspace]\bin\dspace-handle.bat
[dspace]\bin\InstallApp-NT.bat.in -> [dspace]\bin\install-dspace-handle.bat
[dspace]\bin\UninstallApp-NT.bat.in -> [dspace]\bin\uninstall-dspace-handle.bat

The Wrapper.exe file is the actual Wrapper executable. The three batch files are used to run DSpace in a console, and to install and remove it as an NT Service. These scripts should not require any modification. They do assume that the wrapper.conf file will be located within a conf directory one level up,

../conf/wrapper.conf

. If you wish to locate this file someplace else, then the three batch files will require that small modification.

5) Copy the following files from wrapper\lib to the dspace\config directory. NOTE: Do NOT place the following files the dspace\lib directory as they will be overwritten upon a DSpace rebuild.

[wrapper]\lib\Wrapper.DLL
[wrapper]\lib\wrapper.jar

The Wrapper.DLL file is a native library required by the portion of the Wrapper which runs within the JVM. The wrapper.jar file contains all of the Wrapper classes

6) The Wrapper requires a configuration file which needs to be copied from

[wrapper]\conf

to the

[dspace]\config

directory. Ensure that the .in extension is removed from the wrapper.conf file.

[wrapper]\src\conf\wrapper.conf.in

7) The following batch files will then need to be updated to tell the wrapper the location of the config file:

[dspace]\bin\dspace-handle.bat
[dspace]\bin\install-dspace-handle.bat
[dspace]\bin\uninstall-dspace-handle.bat

Locate the line:

set _WRAPPER_CONF="%_REALPATH%..\conf\wrapper.conf" and modify to
set _WRAPPER_CONF="%_REALPATH%..\config\wrapper.conf"

Save and close each of the batch files. If you wish to relocate the configuration file, you are free to do so. You will need to modify the batch scripts copied into the bin directory above, to reflect the new location.

8) To ensure that the wrapper files are not over written, they will need to be copied into the follwing

[dspace-src]

directories:

[dspace]\bin\wrapper.exe -> [dspace-src]\dspace\bin\wrapper.exe

[dspace]\bin\dspace-handle.bat -> [dspace-src]\dspace\bin\dspace-handle.bat
[dspace]\bin\install-dspace-handle.bat -> [dspace-src]\dspace\bin\install-dspace-handle.bat
[dspace]\bin\uninstall-dspace-handle.bat -> [dspace-src]\dspace\bin\uninstall-dspace-handle.bat

Editing the config file

When editing the configuration file

[dspace]

is the absolute path i.e.

C:/DSpace

.

# Java Application Path
# i.e. wrapper.java.command=C:/Program Files/Java/jdk1.6.0_04/bin/java
wrapper.java.command=[PATH TO JDK]/bin/java

# Java Classpath (include wrapper.jar)  Add class path elements as needed starting from 1
wrapper.java.classpath.1=[dspace]/config/wrapper.jar
wrapper.java.classpath.2=[dspace]/lib/handle.jar
wrapper.java.classpath.3=[dspace]/lib/*.jar
wrapper.java.classpath.4=[dspace]/config/templates/*
wrapper.java.classpath.5=[dspace]/config/dspace.cfg

# Java Library Path (location of Wrapper.DLL or libwrapper.so)
wrapper.java.library.path.1=[dspace]/config

# Java Additional Parameters
wrapper.java.additional.1=-Ddspace.configuration=[dspace]/config/dspace.cfg
wrapper.java.additional.2=-Ddspace.log.init.disable=true
wrapper.java.additional.3=-Dlog4j.configuration=log4j-handle-plugin.properties

# Application parameters required to start handle server.  Add parameters as needed starting from 1
wrapper.app.parameter.1=net.handle.server.Main
wrapper.app.parameter.2=[dspace]/handle-server

# Log file to use for wrapper output logging. This needs to be modified from logs to log to write to the DSpace logging directory.
wrapper.logfile=../log/wrapper.log

# Name of the service
wrapper.ntservice.name=DSpaceHandle

# Display name of the service
wrapper.ntservice.displayname=DSpace Handle Service

# Description of the service
wrapper.ntservice.description=DSpace Handle Service

Testing the Wrapper Installation

1) The Handle Server can be run by executing the

[dspace]\bin\DSpace-Handle.bat

script. A terminal window should open as the server loads (see below)

2) Shutdown the handle server by executing CTRL^C in the command window and select Y.

Installing the Handle Server as a Windows Service

1) Once the handle server has been tested and is functioning correctly, it can be installed as a windows service.

2) Execute the following batch script to install the Handle Server as a Windows service:

[dspace]\bin\install-dspace-handle.bat

Checking the Windows Services GUI will show the installed service

3) To uninstall the service, execute the following script:

[dspace]\bin\uninstall-dspace-handle.bat

Troubleshooting

If a similar error message to below is displayed:

WrapperManager Error: Unexpected exception opening backend socket: java.net.SocketException: Network is unreachable: connect

1) Ensure ports 2641 and 8000 (TCP/UDP) are open in both your server firewall and institutions firewall.

2) Ensure your server's correct IP is specified in the dspace/handle-server/config.dct