Contents |
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.
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.
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.
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" |
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 |
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 |
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.
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 |
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