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" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" 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.  You should set the URIEncoding even if you are running Tomcat behind a proxy (Apache HTTPD, Nginx, etc.) via AJP.

  • 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 (httphttps://www.mortbayeclipse.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.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
      language html/xml
      <Connector port="8443" URIEncoding="UTF-8"  maxThreads minSpareThreads="150" 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" maxThreads="150" 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.

...

To install your Handle resolver on the host where DSpace runs:

1. To configure your DSpace installation to To configure your DSpace installation to run the handle server, run the following command:

   Code Block
   [dspace]/bin/dspace make-handle-config [dspace]/handle-server

   Ensure that [dspace]/handle-server matches whatever you have in dspace.cfg for the handle.dir property.

   1. If you are using Windows, the proper command is:

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

      Ensure that [dspace]/handle-server matches whatever you have in dspace.cfg for the handle.dir property.

2. Edit the resulting [dspace]/handle-server/config.dct file to include the following lines in the "server_config"clause:

   Code Block
   "storage_type" = "CUSTOM" "storage_class" = "org.dspace.handle.HandlePlugin"

   This tells the Handle server to get information about individual Handles from the DSpace code.

3. Once the configuration file has been generated, you will need to go to http://hdl.handle.net/4263537/5014 to upload the generated sitebndl.zip file. The upload page will ask you for your contact information. An administrator will then create the naming authority/prefix on the root service (known as the Global Handle Registry), and notify you when this has been completed. You will not be able to continue the handle server installation until you receive further information concerning your naming authority.
4. When CNRI has sent you your naming authority prefix, you will need to edit the config.dct file. The file will be found in /[dspace]/handle-server. Look for "300:0.NA/YOUR_NAMING_AUTHORITY". Replace YOUR_NAMING_AUTHORITY with the assigned naming authority prefix sent to you.

5. Now start your handle server (as the dspace user):

   Code Block
   [dspace]/bin/start-handle-server

   1. If you are using Windows, there is a corresponding 'start-handle-server.bat' script:

      Code Block
      [dspace]/bin/start-handle-server.bat

      
      

...

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.

Windows Installation

External database connection pool

Before it builds a pool of database connections, DSpace always tries to look up an existing, pre-configured pool in a directory service (if such a service is provided). Many web application containers supply such a service and can be configured to provide the connection pool to DSpace. If DSpace does not find a pre-configured pool, each web application will fall back to creating its own pool using the settings in local.cfg.

There are some advantages to using an external database pool:

• You can share one pool among several of DSpace's web applications—or even all of them. This can help economize database connections when one application uses many and another few. For example, if XMLUI needs 30 connections to run well at your site under peak load and OAI-PMH needs 5, you could connect them both to a pool of 35 connections, instead of letting each take 30 for a total of 60.
• You can have different pool sizes for the web applications and the command line tools. For example, configure an external pool with generous settings for the web applications, and a much smaller pool for the command line applications in local.cfg. Note: the command line tools cannot use an externally configured pool, and always use the settings in local.cfg to build their own pool.
• External database pooling often allows for more granular configuration of pool parameters and can even provide better performance than DSpace's fallback pooling (see the Tomcat JDBC Connection Pool documentation for more information).

DSpace applications will specifically look for an object named jdbc/dspace. The name is not configurable, but is specified in config/spring/api/core-hibernate.xml if you must know. You must configure the name of the directory object provided to your web application context(s) to match this. See below for an example in Tomcat.

An example in Tomcat

First, you must make the JDBC driver for your database available to Tomcat. For example, the latest PostgreSQL JDBC driver can be downloaded from the PostgreSQL project website and placed in Tomcat's lib directory. The exact location of this directory varies depending on your operating system and Tomcat version, but on Ubuntu 16.04 with Tomcat 7 the location would be /usr/share/tomcat7/lib.

Then add a <Resource> in Tomcat's server.xml to define the pool. The pool name here is global and can be anything you want:

  <GlobalNamingResources>
...
    <Resource
        name='jdbc/instance'
        description='Our DSpace DBMS connection pool'
        type='javax.sql.DataSource'
        auth='Container'
        username='USER'
        password='SECRET'
        driverClassName='org.postgresql.Driver'
        url='jdbc:postgresql://dbms.example.com:5432/dspace'
        initialSize='5'
        maxTotal='50'
        maxIdle='15'
        minIdle='5'
        maxWaitMillis='5000'
        />
...
  </GlobalNamingResources>

Then add a <ResourceLink> to each web application's context configuration. The name parameter here is local to the application context, and must be jdbc/dspace:

<Context
...
  <ResourceLink
    name='jdbc/dspace'
    global='jdbc/instance'
    type='javax.sql.DataSource'
   />
...
</Context>

Notice that the global parameter in the ResourceLink matches the name of the global Resource. See the JNDI Datasource HOW-TO for more information about this configuration.

Windows Installation

Essentially installing on Windows is the same as installing on Unix so Essentially installing on Windows is the same as installing on Unix so please refer back to the main Installation Instructions section section.

• Download the DSpace source from SourceForge GitHub and unzip it (WinZip will do this)
• If you install PostgreSQL, it's recommended to select to install the pgAdmin III tool. It provides a nice User Interface for interacting with PostgreSQL databases.
• For all path separators use forward slashes (e.g. "/"). For example: "C:/dspace" is a valid Windows path.  But, be warned that "C:\dspace" IS INVALID and will cause errors.

...

• 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-installer/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.

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

General DSpace Issues

...