All Versions
- DSpace 7.x (Current Release)
- DSpace 8.x (Unreleased)
- DSpace 6.x (EOL)
- DSpace 5.x (EOL)
- More Versions...
Table of Contents | ||||||
---|---|---|---|---|---|---|
|
Warning | ||
---|---|---|
| ||
This page is OBSOLETE and contains old DSpace 6 installation instructions. It is temporarily kept here to ensure all old instructions find a new "home" in the DSpace 7 docs. For DSpace 7 Installation instructions see Try out DSpace 7 |
Since some users might want to get their test version up and running as fast as possible, offered below is an unsupported outline of getting DSpace to run quickly in a Unix-based environment using the DSpace source release.
...
Code Block | ||
---|---|---|
| ||
useradd -m dspace gzip xzf dspace-6.x-src-release.tar.gz createuser --username=postgres --no-superuser --pwprompt dspace createdb --username=postgres --owner=dspace --encoding=UNICODE dspace psql --username=postgres dspace -c "CREATE EXTENSION pgcrypto;" cd [dspace-source]/dspace/config/ cp local.cfg.EXAMPLE local.cfg vi local.cfg mkdir [dspace] chown dspace [dspace] su - dspace cd [dspace-source] mvn package cd [dspace-source]/dspace/target/dspace-installer ant fresh_install cp -r [dspace]/webapps/* [tomcat]/webapps /etc/init.d/tomcat start [dspace]/bin/dspace create-administrator |
You can install and run DSpace on most modern PC, laptop or server hardware. However, if you intend to run DSpace for a large community of potential end users, carefully review the Hardware Recommendations in the User FAQ
The list below describes the third-party components and tools you'll need to run a DSpace server. These are just guidelines. Since DSpace is built on open source, standards-based tools, there are numerous other possibilities and setups.
Also, please note that the configuration and installation guidelines relating to a particular tool below are here for convenience. You should refer to the documentation for each individual component for complete and up-to-date details. Many of the tools are updated on a frequent basis, and the guidelines below may become out of date.
OpenJDK download and installation instructions can be found here http://openjdk.java.net/install/. Most operating systems provide an easy path to install OpenJDK. Just be sure to install the full JDK (development kit), and not the JRE (which is often the default example).
...
Note | ||
---|---|---|
| ||
Older versions of Java are unsupported. This includes JDK v7-10. Newer versions of Java may work (e.g. JDK v12-16), but we do not recommend running them in Production. We highly recommend running only Java LTS (Long Term Support) releases in Production, as non-LTS releases may not receive ongoing security fixes. As of this DSpace release, JDK11 is the most recent Java LTS release, with the next one (JDK17) being due sometime around September 2021. As soon as the next Java LTS release is available, we will analyze it for compatibility with this release of DSpace. For more information on Java releases, see the Java roadmaps for Oracle and/or OpenJDK. |
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.
Maven can be downloaded from http://maven.apache.org/download.html
You can configure a proxy to use for some or all of your HTTP requests in Maven. The username and password are only required if your proxy requires basic authentication (note that later releases may support storing your passwords in a secured keystore‚ in the meantime, please ensure your settings.xml file (usually ${user.home}/.m2/settings.xml) is secured with permissions appropriate for your operating system).
...
Code Block |
---|
<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 is required for the second stage of the build process (deploying/installing the application). First, Maven is used to construct the installer ([dspace-source]/dspace/target/dspace-installer
), after which Ant is used to install/deploy DSpace to the installation directory.
Ant can be downloaded from the following location: http://ant.apache.org
Note | ||
---|---|---|
| ||
Active development/testing on DSpace 7 has occurred on PostgreSQL v11. However, it is likely that the backend would also function on PostgreSQL v9.4 - v10. At this time we have not performed sufficient testing on these earlier versions to add them to the prerequisites listing. |
postgresql.conf
: uncomment the line starting: listen_addresses = 'localhost'
. This is the default, in recent PostgreSQL releases, but you should at least check it.Then tighten up security a bit by editing pg_hba.conf
and adding this line:
Code Block |
---|
host dspace dspace 127.0.0.1 255.255.255.255 md5 |
This should appear before any lines matching all
databases, because the first matching rule governs.
tnsnames.ora
and listener.ora
files to the database the Oracle server.[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] |
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 | ||
---|---|---|
| ||
<!-- Define a non-SSL HTTP/1.1 Connector on port 8080 --> <Connector port="8080" minSpareThreads="25" enableLookups="false" redirectPort="8443" 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.
Solr can be obtained at the Apache Software Foundation site for Lucene and Solr. You may wish to read portions of the quick-start tutorial to make yourself familiar with Solr's layout and operation. Unpack a Solr .tgz or .zip archive in a place where you keep software that is not handled by your operating system's package management tools, and arrange to have it running whenever DSpace is running. You should ensure that Solr's index directories will have plenty of room to grow. You should also ensure that port 8983 is not in use by something else, or configure Solr to use a different port.
...
It is not necessary to dedicate a Solr instance to DSpace, if you already have one and want to use it. Simply copy DSpace's cores to a place where they will be discovered by Solr. See below.
Currently, there is a known bug in DSpace where a third-party Maven Module expects git
to be available (in order to support the ./dspace version
commandline tool). We are working on a solution within this ticket:
Jira | ||||||
---|---|---|---|---|---|---|
|
For the time being, you can work around this problem by installing Git locally: https://git-scm.com/downloads
Two different distributions are available for DSpace, both of which require you to build the distribution using Apache Maven 3. The steps that are required to execute the build are identical. In a nutshell, the binary release build will download pre-compiled parts of DSpace, while the building the source release will compile most of DSpace's source code on your local machine.
...
Before beginning an installation, it is important to get a general understanding of the DSpace directories and the names by which they are generally referred. (Please attempt to use these below directory names when asking for help on the DSpace Mailing Lists, as it will help everyone better understand what directory you may be referring to.)
...
If you ever notice that many files seems to have duplicates under [dspace-source]/dspace/target
do not worry about it. This "target" directory will be used by Maven for the build process and you should not change any file in it unless you know exactly what you are doing.
This method gets you up and running with DSpace quickly and easily. It is identical in both the Default Release and Source Release distributions.
...
In order to set up some communities and collections, you'll need to login as your DSpace Administrator (which you created with create-administrator
above) and access the administration UI in either the JSP or XML user interface.
The above installation steps are sufficient to set up a test server to play around with, but there are a few other steps and options you should probably consider before deploying a DSpace production site.
A few DSpace features require that a script is run regularly (via cron, or similar):
...
For much more information on recommended scheduled tasks, please see Scheduled Tasks via Cron.
In order to deploy a multilingual version of DSpace you have to configure two parameters in [dspace-source]/dspace/config/local.cfg
:
...
According to the languages you wish to support, you have to make sure that all the i18n related files are available. See the Configuring Multilingual Support section for the JSPUI or the Multilingual Support for XMLUI in the configuration documentation.
If your DSpace is configured to have users login with a username and password (as opposed to, say, client Web certificates), then you should consider using HTTPS. Whenever a user logs in with the Web form (e.g. dspace.myuni.edu/dspace/password-login) their DSpace password is exposed in plain text on the network. This is a very serious security risk since network traffic monitoring is very common, especially at universities. If the risk seems minor, then consider that your DSpace administrators also login this way and they have ultimate control over the archive.
...
Loosely based on http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html.
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 |
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 |
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 |
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" URIEncoding="UTF-8" minSpareThreads="25" enableLookups="false" disableUploadTimeout="true" 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 | ||
---|---|---|
| ||
<Connector port="8080" minSpareThreads="25" enableLookups="false" redirectPort="8443" /> |
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.
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 |
Warning |
---|
When using Apache 2.4.2 (and lower) in front of a DSpace webapp deployed in Tomcat, mod_proxy_ajp and possibly mod_proxy_http breaks the connection to the back end (Tomcat) prematurely leading to response mixups. This is reported as bug CVE-2012-3502 ( http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2012-3502 ) of Apache and fixed in Apache 2.4.3 (see http://www.apache.org/dist/httpd/CHANGES_2.4). The 2.2.x branch hasn't shown this problem only the 2.4.x branch has. |
...
In your Tomcat's server.xml
, ensure that the AJP Connector is UNCOMMENTED. Usually this runs on port 8009, but you can decide to change the port if you desire
Code Block |
---|
<!-- Define an AJP 1.3 Connector on port 8009 --> <Connector port="8009" protocol="AJP/1.3" /> |
sudo a2enmod proxy proxy_ajp
Create a new Virtual Host in Apache HTTP Server to represent your DSpace site. Here's a basic example of a Virtual Host responding to any port 80 requests for "my.dspace.edu":
Code Block |
---|
<VirtualHost *:80> # Obviously, replace the ServerName with your DSpace site URL ServerName my.dspace.edu ## Apache HTTP Server Logging Settings - modify how you see fit ErrorLog ${APACHE_LOG_DIR}/my.dspace.edu-error.log CustomLog ${APACHE_LOG_DIR}/my.dspace.edu-access.log combined # Possible values include: debug, info, notice, warn, error, crit, alert, emerg. LogLevel warn # There are many more configurations available for Virtual Hosts, # see the documentation for more details # http://httpd.apache.org/docs/2.4/vhosts/ </VirtualHost> |
If you want your site to also respond to SSL requests, you'll need to install and enable "mod_ssl" and create a second Virtual Host to respond to port 443 requests. An example is provided below. But much more details are available in the Apache HTTP SSL Documentation and the mod_ssl documentation
Code Block |
---|
<VirtualHost *:443> # Obviously, replace the ServerName with your DSpace site URL ServerName my.dspace.edu # You can have SSL Apache logging settings here too (see the port 80 example above) # Configure your SSL Certificate (you must create one, obviously) # See the "keytool" instructions above for examples of creating this certificate # There are also many good guides on the web for generating SSL certificates for Apache SSLEngine on SSLCertificateChainFile /path/to/your/chainfile.crt SSLCertificateFile /path/to/your/public-cert.crt SSLCertificateKeyFile /path/to/your/private-key.key # More information on SSL configurations can be found in the mod_ssl documentation # http://httpd.apache.org/docs/2.4/mod/mod_ssl.html </VirtualHost> |
Info | ||
---|---|---|
| ||
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:
|
In each of your Apache HTTP Virtual Hosts (see above), use "ProxyPass" configurations to configure the redirects from Apache HTTP Server to Apache Tomcat. The exact configurations depend on whether you want to redirect ALL requests to Tomcat, or just certain paths. Here's a basic example. But much more information and examples can be found in the mod_proxy documentation
Code Block |
---|
# These are just examples. THEY LIKELY WILL NEED MODIFICATION. # Again, remember to add these to your EXISTING <VirtualHost> settings <VirtualHost> ... (existing settings) ... # If there's a single path you do NOT want redirected, you can use ! to ignore it # In this case any requests to "/ignored_path" will be handled by Apache HTTPD and NOT forwarded to Tomcat ProxyPass /ignored_path ! # These configurations say: By default, redirect ALL requests to port 8009 # (The port MUST match the port of your Tomcat AJP Connector. By default this usually is 8009) ProxyPass / ajp://localhost:8009/ ProxyPassReverse / ajp://localhost:8009/ # You may also wish to provide additional "mod_proxy" configurations, # for more examples and details see the documentation at # http://httpd.apache.org/docs/2.4/mod/mod_proxy.html </VirtualHost> |
First a few facts to clear up some common misconceptions:
...
You can either use a Handle server running on the same machine as DSpace, or you can install it on a separate machine. Installing it on the same machine is a little bit easier. If you install it on a separate machine, you can use one Handle server for more than one DSpace installation.
Note |
---|
We recommend configuring your Handle server without a passphrase, as the current DSpace If you choose to set a passphrase, you may need to start the Handle Server via: |
...
Note that since the DSpace code manages individual Handles, administrative operations such as Handle creation and modification aren't supported by DSpace's Handle server.
Warning | ||||||||
---|---|---|---|---|---|---|---|---|
The option to run the Handle resolver on a separate machine is not yet available in DSpace 7 codebase. See this ticket:
|
...
Please note: The Handle Server will only start if it is able to connect to at least one running DSpace Installation. It only resolves the handles of the DSpace Installations that were running when it was started.
Instead of using the describd plugin above, you can configure a Handle server (version 8+) to resolve handles based on a template. Template handle require less configuration than the plugin, and do not require an additional download. However, there are two things to keep in mind when using template handles:
...
This configuration is a minimal example of how to configure template handles for DSpace. For more details about configuing template handles, see the Handle Technical Manual, Chapter 11.
If you need to update the handle prefix on items created before the CNRI registration process you can run the [dspace]/bin/dspace 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:
...
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.
To aid web crawlers index the content within your repository, you can make use of sitemaps. There are currently two forms of sitemaps included in DSpace: Google sitemaps and HTML sitemaps.
...
Info |
---|
More information on why we highly recommend enabling sitemaps can be found at Search Engine Optimization (SEO). |
DSpace uses the Apache Solr application underlaying the statistics. You will need a working installation of Solr, which you can get from the Apache Software Foundation. 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.
If you wish to record the geographic locations of clients in usage statistics records, you will need to install and maintain a copy of MaxMind's GeoLite database. You will also need to configure its location as the value of usage-statistics.dbfile
in config/modules/usage-statistics.cfg
.
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
.
...
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.
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
.
...
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.
Essentially installing on Windows is the same as installing on Unix so please refer back to the main 104566943 section.
The administrator needs to check the installation to make sure all components are working. Here is list of checks to be performed. In brackets after each item, it the associated component or components that might be the issue needing resolution.
In any software project of the scale of DSpace, there will be bugs. Sometimes, a stable version of DSpace includes known bugs. We do not always wait until every known bug is fixed before a release. If the software is sufficiently stable and an improvement on the previous release, and the bugs are minor and have known workarounds, we release it to enable the community to take advantage of those improvements.
...
Please see the DSpace bug tracker for further information on current bugs, and to find out if the bug has subsequently been fixed. This is also where you can report any further bugs you find.
In an ideal world everyone would follow the above steps and have a fully functioning DSpace. Of course, in the real world it doesn't always seem to work out that way. This section lists common problems that people encounter when installing DSpace, and likely causes and fixes. This is likely to grow over time as we learn about users' experiences.
ant fresh_install
: There are two common errors that occur.If your error looks like this:
Code Block |
---|
[java] 2004-03-25 15:17:07,730 INFO org.dspace.storage.rdbms.InitializeDatabase @ Initializing Database [java] 2004-03-25 15:17:08,816 FATAL org.dspace.storage.rdbms.InitializeDatabase @ Caught exception: [java] org.postgresql.util.PSQLException: Connection refused. Check that the hostname and port are correct and that the postmaster is accepting TCP/IP connections. [java] at org.postgresql.jdbc1.AbstractJdbc1Connection.openConnection(AbstractJd bc1Connection.java:204) [java] at org.postgresql.Driver.connect(Driver.java:139) |
it usually means you haven't yet added the relevant configuration parameter to your PostgreSQL configuration (see above), or perhaps you haven't restarted PostgreSQL after making the change. Also, make sure that the db.username and db.password properties are correctly set in [dspace]/config/dspace.cfg. An easy way to check that your DB is working OK over TCP/IP is to try this on the command line:
Code Block |
---|
psql -U dspace -W -h localhost |
Enter the dspace database password, and you should be dropped into the psql tool with a dspace=> prompt.
Another common error looks like this:
Code Block |
---|
[java] 2004-03-25 16:37:16,757 INFO org.dspace.storage.rdbms.InitializeDatabase @ Initializing Database [java] 2004-03-25 16:37:17,139 WARN org.dspace.storage.rdbms.DatabaseManager @ Exception initializing DB pool [java] java.lang.ClassNotFoundException: org.postgresql.Driver [java] at java.net.URLClassLoader$1.run(URLClassLoader.java:198) [java] at java.security.AccessController.doPrivileged(Native Method) [java] at java.net.URLClassLoader.findClass(URLClassLoader.java:186) |
This means that the PostgreSQL JDBC driver is not present in [dspace]/lib. See above.
ps -ef | grep java
and look for Tomcat's Java processes. If they stay around after running Tomcat's shutdown.sh script, trying running kill
on them (or kill -9
if necessary), then starting Tomcat again.ps -ef | grep postgres
You might see some processes like this:
Code Block |
---|
dspace 16325 1997 0 Feb 14 ? 0:00 postgres: dspace dspace 127.0.0.1 idle in transaction |
This is normal. DSpace maintains a 'pool' of open database connections, which are re-used to avoid the overhead of constantly opening and closing connections. If they're 'idle' it's OK; they're waiting to be used.
However sometimes, if something went wrong, they might be stuck in the middle of a query, which seems to prevent other connections from operating, e.g.:
Code Block |
---|
dspace 16325 1997 0 Feb 14 ? 0:00 postgres: dspace dspace 127.0.0.1 SELECT |
This means the connection is in the middle of a SELECT operation, and if you're not using DSpace right that instant, it's probably a 'zombie' connection. If this is the case, try running kill
on the process, and stopping and restarting Tomcat.