Page History

...

• Apache Tomcat 7 or later. Tomcat can be downloaded from the following location: http://tomcat.apache.org.
  
  • The Tomcat owner (i.e. the user that Tomcat runs as) must have read/write access to the DSpace installation directory (i.e. [dspace]). There are a few common ways this may be achieved:

    • One option is to specifically give the Tomcat user (often named "tomcat") ownership of the [dspace] directories, for example:

      Code Block
      # Change [dspace] and all subfolders to be owned by "tomcat" chown -R tomcat:tomcat [dspace]

      
      

    • Another option is to have Tomcat itself run as a new user named "dspace" (see installation instructions below).  Some operating systems make modifying the Tomcat "run as" user easily modifiable via an environment variable named TOMCAT_USER.  This option may be more desireable if you have multiple Tomcat instances running, and you do not want all of them to run under the same Tomcat owner.
  • You need to ensure that Tomcat has a) enough memory to run DSpace and b) uses UTF-8 as its default file encoding for international character support. So ensure in your startup scripts (etc) that the following environment variable is set: JAVA_OPTS="-Xmx512M -Xms64M -Dfile.encoding=UTF-8"

  • Modifications in [tomcat]/conf/server.xml : You also need to alter Tomcat's default configuration to support searching and browsing of multi-byte UTF-8 correctly. You need to add a configuration option to the <Connector> element in [tomcat]/config/server.xml: URIEncoding="UTF-8"e.g. if you're using the default Tomcat config, it should read:

    Code Block
    language html/xml
    <!-- Define a non-SSL HTTP/1.1 Connector on port 8080 --> <Connector port="8080" minSpareThreads="25" enableLookups="false" redirectPort="8443" acceptCount="100" connectionTimeout="20000" disableUploadTimeout="true" URIEncoding="UTF-8"/>

    You may change the port from 8080 by editing it in the file above, and by setting the variable CONNECTOR_PORT in server.xml.

  • Tomcat 8 and above is using at least Java 1.7 for JSP compilation. However, by default, Tomcat 7 uses Java 1.6 for JSP compilation. If you want to use Java 1.7 in your .jsp files, you have to change the configuration of Tomcat 7. Edit the file called web.xml in the configuration directory of your Tomcat instance (${CATALINA_HOME}/conf in Tomcat notation). Look for a servlet definition using the org.apache.jasper.servlet.JSPServlet servlet-class and add two init parameters compilerSourceVM and compilerTargetVM as you see it in the example below. Then restart Tomcat.

    Code Block
    language xml title ${CATALINA_BASE}/conf/web.xml
    <servlet> <servlet-name>jsp</servlet-name> <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class> <init-param> <param-name>fork</param-name> <param-value>false</param-value> </init-param> <init-param> <param-name>xpoweredBy</param-name> <param-value>false</param-value> </init-param> <init-param> <param-name>compilerSourceVM</param-name> <param-value>1.7</param-value> </init-param> <init-param> <param-name>compilerTargetVM</param-name> <param-value>1.7</param-value> </init-param> <load-on-startup>3</load-on-startup> </servlet>

    
    

• Jetty or Caucho Resin DSpace will also run on an equivalent servlet Engine, such as Jetty (http://www.mortbay.org/jetty/index.html) or Caucho Resin (http://www.caucho.com/). Jetty and Resin are configured for correct handling of UTF-8 by default.

...

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.xmlTomcat 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
      language html/xml
      <Connector port="8443" URIEncoding="UTF-8"  minSpareThreads="25" enableLookups="false" disableUploadTimeout="true" acceptCount="100" 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" truststorePass="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
      language html/xml
      <Connector port="8080" minSpareThreads="25" enableLookups="false" redirectPort="8443" acceptCount="100" />

      
      

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. 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'

      You should be prompted for a password to protect the private key.

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

      
      

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

...