Implementing the Handle Server on Windows using the Tanuki Service Wrapper
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/
Registering for a Handle
1) The Handle server code is included with the DSpace code in
. 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
by running the following command and completing the questions:
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
4) The registration process should take about one week. Once completed you should receive a handle which can be used to update 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:
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
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:
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
to include the following clause in the "server_config" clause:
2) Update all references to YOUR_NAMING_AUTHORITY to your handle prefix. i.e.:
Installing the Tanuki Service Wrapper
1) Download the Tanuki Java service wrapper and extract to wrapper
2) Copy the following file from
3) Copy the following files from
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.
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,
. If you wish to locate this file someplace else, then the three batch files will require that small modification.
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
directory. Ensure that the .in extension is removed from the wrapper.conf file.
7) The following batch files will then need to be updated to tell the wrapper the location of the config file:
Locate the line:
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
Editing the config file
When editing the configuration file
is the absolute path i.e.
Testing the Wrapper Installation
1) The Handle Server can be run by executing the
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:
Checking the Windows Services GUI will show the installed service
3) To uninstall the service, execute the following script:
If a similar error message to below is displayed:
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