Page History

...

Only Oracle's Java has been tested with each release and is known to work correctly. Other flavors of Java may pose problems.

Apache Maven 2.2.x or higher (Java build tool)

Maven is necessary in the first stage of the build process to assemble the installation package for your DSpace instance. It gives you the flexibility to customize DSpace using the existing Maven projects found in the _\[dspace-source\]/dspace/modules_ directory or by adding in your own Maven project to build the installation package for DSpace, and apply any custom interface "overlay" changes.

...

<settings>
  .
  .
  <proxies>
   <proxy>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.somewhere.com</host>
      <port>8080</port>
      <username>proxyuser</username>
      <password>somepassword</password>
      <nonProxyHosts>www.google.com|*.somewhere.com</nonProxyHosts>
    </proxy>
  </proxies>
  .
  .
</settings> 

Apache Ant 1.7 or later (Java build tool)

...

1. For Production use: Follow this procedure to set up SSL on your server. Using a "real" server certificate ensures your users' browsers will accept it without complaints. In the examples below, $CATALINA_BASE is the directory under which your Tomcat is installed.
   1. Create a Java keystore for your server with the password changeit, and install your server certificate under the alias "tomcat". This assumes the certificate was put in the file server.pem:

      Code Block
      $JAVA_HOME/bin/keytool -import -noprompt -v -storepass changeit -keystore $CATALINA_BASE/conf/keystore -alias tomcat -file myserver.pem

   2. Install the CA (Certifying Authority) certificate for the CA that granted your server cert, if necessary. This assumes the server CA certificate is in ca.pem:

      Code Block
      $JAVA_HOME/bin/keytool -import -noprompt -storepass changeit -trustcacerts -keystore $CATALINA_BASE/conf/keystore -alias ServerCA -file ca.pem

   3. Optional – ONLY if you need to accept client certificates for the X.509 certificate stackable authentication module See the configuration section for instructions on enabling the X.509 authentication method. Load the keystore with the CA (certifying authority) certificates for the authorities of any clients whose certificates you wish to accept. For example, assuming the client CA certificate is in client1.pem:

      Code Block
      $JAVA_HOME/bin/keytool -import -noprompt -storepass changeit -trustcacerts -keystore $CATALINA_BASE/conf/keystore -alias client1 -file client1.pem

   4. Now add another Connector tag to your server.xml Tomcat configuration file, like the example below. The parts affecting or specific to SSL are shown in bold. (You may wish to change some details such as the port, pathnames, and keystore password)

      Code Block
      <Connector port="8443" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="100" debug="0" scheme="https" secure="true" sslProtocol="TLS" keystoreFile="conf/keystore" keystorePass="changeit" clientAuth="true" - ONLY if using client X.509 certs for authentication! truststoreFile="conf/keystore" trustedstorePass="changeit" />

      Also, check that the default Connector is set up to redirect "secure" requests to the same port as your SSL connector, e.g.:

      Code Block
      <Connector port="8080" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" redirectPort="8443" acceptCount="100" debug="0" />

2. Quick-and-dirty Procedure for Testing: If you are just setting up a DSpace server for testing, or to experiment with HTTPS, then you don't need to get a real server certificate. You can create a "self-signed" certificate for testing; web browsers will issue warnings before accepting it but they will function exactly the same after that as with a "real" certificate. In the examples below, $CATALINA_BASE is the directory under which your Tomcat is installed.
   1. Optional – ONLY if you don't already have a server certificate. Follow this sub-procedure to request a new, signed server certificate from your Certifying Authority (CA):
      • Create a new key pair under the alias name "tomcat". When generating your key, give the Distinguished Name fields the appropriate values for your server and institution. CN should be the fully-qualified domain name of your server host. Here is an example:

        Code Block
        $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -keysize 1024 \ -keystore $CATALINA_BASE/conf/keystore -storepass changeit -validity 365 \ -dname 'CN=dspace.myuni.edu, OU=MIT Libraries, O=Massachusetts Institute of Technology, L=Cambridge, S=MA, C=US'

      • Then, create a CSR (Certificate Signing Request) and send it to your Certifying Authority. They will send you back a signed Server Certificate. This example command creates a CSR in the file tomcat.csr

        Code Block
        $JAVA_HOME/bin/keytool -keystore $CATALINA_BASE/conf/keystore -storepass changeit \ -certreq -alias tomcat -v -file tomcat.csr

      • Before importing the signed certificate, you must have the CA's certificate in your keystore as a trusted certificate. Get their certificate, and import it with a command like this (for the example mitCA.pem):

        Code Block
        $JAVA_HOME/bin/keytool -keystore $CATALINA_BASE/conf/keystore -storepass changeit \ -import -alias mitCA -trustcacerts -file mitCA.pem

      • Finally, when you get the signed certificate from your CA, import it into the keystore with a command like the following example: (cert is in the file signed-cert.pem)

        Code Block
        $JAVA_HOME/bin/keytool -keystore $CATALINA_BASE/conf/keystore -storepass changeit \ -import -alias tomcat -trustcacerts -file signed-cert.pem

        Since you now have a signed server certificate in your keystore, you can, obviously, skip the next steps of installing a signed server certificate and the server CA's certificate.
   2. Create a Java keystore for your server with the password changeit, and install your server certificate under the alias "tomcat". This assumes the certificate was put in the file server.pem:

      Code Block
      $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -keystore $CATALINA_BASE/conf/keystore -storepass changeit

      When answering the questions to identify the certificate, be sure to respond to "First and last name" with the fully-qualified domain name of your server (e.g. test-dspace.myuni.edu). The other questions are not important.
   3. Optional – ONLY if you need to accept client certificates for the X.509 certificate stackable authentication module See the configuration section for instructions on enabling the X.509 authentication method. Load the keystore with the CA (certifying authority) certificates for the authorities of any clients whose certificates you wish to accept. For example, assuming the client CA certificate is in client1.pem:

      Code Block
      $JAVA_HOME/bin/keytool -import -noprompt -storepass changeit -trustcacerts -keystore $CATALINA_BASE/conf/keystore -alias client1 -file client1.pem

   4. Follow the procedure in the section above to add another Connector tag, for the HTTPS port, to your server.xml file.

...

If you are using X.509 Client Certificates for authentication: add these configuration options to the appropriate httpd configuration file, e.g. ssl.conf, and be sure they are in force for the virtual host and namespace locations dedicated to DSpace:

        ##  SSLVerifyClient can be "optional" or
	"require"
        SSLVerifyClient optional
        SSLVerifyDepth  10
        SSLCACertificateFile
	path-to-your-client-CA-certificate
        SSLOptions StdEnvVars ExportCertData

Now consult the Apache Jakarta Tomcat Connector documentation to configure the mod_jk (note: NOTmod_jk2) module. Select the AJP 1.3 connector protocol. Also follow the instructions there to configure your Tomcat server to respond to AJP.

...

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

This script 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.

...

# Generate sitemaps


0 6 * * * [dspace]/bin/dspace generate-sitemaps

DSpace Statistics

DSpace uses the Apache Solr application underlaying the statistics. There is no need to download any separate software. All the necessary software is included. To understand all of the configuration property keys, the user should refer to DSpace Statistic Configuration for detailed information.

...

1. Wiki Markup
   Attempt to re-run the automatic installer from your DSpace Source Directory (\[dspace-source\]). This will attempt to automatically download the database file, unzip it and install it into the proper location:

   Code Block
   ant update_geolite

   • Wiki Markup
     NOTE: If the location of the GeoLite Database file is known to have changed, you can also run this auto-installer by passing it the new URL of the GeoLite Database File: {{ant \-Dgeolite=\[full-URL-of-geolite\] update_geolite}}

2. OR, you can manually install the file by performing these steps yourself:
   • First, download the latest GeoLite Database file from http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz^{Image Removed}
   • Next, unzip that file to create a file named GeoLiteCity.dat

   • Wiki Markup
     Finally, move or copy that file to your DSpace installation, so that it is located at {{\[dspace\]/config/GeoLiteCity.dat}}.

...

• GeoLiteCity Database file fails to download or install, when you run ant fresh_install: There are two common errors that may occur:
  • If your error looks like this:

    Code Block
    [get] Error getting http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz to /usr/local/dspace/config/GeoLiteCity.dat.gz BUILD FAILED /dspace-release/dspace/target/dspace-1.7.2-build.dir/build.xml:931: java.net.ConnectException: Connection timed out

    it means that you likely either (a) don't have an internet connection to download the necessary GeoLite Database file (used for DSpace Statistics), or (b) the GeoLite Database file's URL is no longer valid. You should be able to resolve this issue by following the "Manually Installing/Updating GeoLite Database File" instructions above.
  • Another common message looks like this:

    Code Block
    [echo] WARNING : FAILED TO DOWNLOAD GEOLITE DATABASE FILE [echo] (Used for DSpace Solr Usage Statistics)

    Again, this means the GeoLite Database file cannot be downloaded or is unavailable for some reason. You should be able to resolve this issue by following the "Manually Installing/Updating GeoLite Database File" instructions above.

...