All Versions
- DSpace 7.x (Current Release)
- DSpace 8.x (Unreleased)
- DSpace 6.x (EOL)
- DSpace 5.x (EOL)
- More Versions...
Contribute to the DSpace Development Fund
The newly established DSpace Development Fund supports the development of new features prioritized by DSpace Governance. For a list of planned features see the fund wiki page.
Try out DSpace 7 before you install
If you'd like to quickly try out DSpace 7 before a full installation, see Try out DSpace 7 for instructions on a quick install via Docker.
As of version 7 (and above), the DSpace application is split into a "frontend" (User Interface) and a "backend" (Server API). Most institutions will want to install BOTH. However, you can decide whether to run them on the same machine or separate machines.
We recommend installing the Backend first, as the Frontend requires a valid Backend to run properly.
Work in progress (Feedback welcome)
These installation instructions are a work-in-progress and based heavily on the DSpace 6.x installation instructions. Feedback or improvements are welcome.
Make sure to install the JDK and not just the JRE
At this time, DSpace requires the full JDK (Java Development Kit) be installed, rather than just the JRE (Java Runtime Environment). So, please be sure that you are installing the full JDK and not just the JRE.
Only JDK11 is fully supported
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).
Example:
<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>
While Apache Ant recommends using v1.10.x for Java 11, we've also had some success with recent versions of 1.9.x (specifically v1.9.15 seems to work fine with Java 11). That said, earlier versions of v1.9.x are not compatible with Java 11.
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
PostgreSQL v9.4 to v11 will likely work, but earlier versions are less well tested.
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.
DSpace 7 will definitely not function on versions below 9.4 as DSpace requires installing and running the pgcrypto extension (see below) v1.1, which was not available until PostgreSQL v9.4.
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:
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.Make sure to install Solr with Authentication disabled (which is the default). DSpace does not yet support authentication to Solr (see https://github.com/DSpace/DSpace/issues/3169). Instead, we recommend placing Solr behind a firewall and/or ensuring port 8983 (which Solr runs on) is not available for public/anonymous access on the web. Solr only needs to be accessible to requests from the DSpace backend.
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.
If you are looking for a good place to put Solr, consider /opt
or /usr/local
. You can simply unpack Solr in one place and use it. Or you can configure Solr to keep its indexes elsewhere, if you need to – see the Solr documentation for how to do this.
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.
[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:
# 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:
<!-- 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.
Optionally, if you wish to record the geographic locations of clients in DSpace usage statistics records, you will need to install (and regularly update) one of the following:
geoipupdate
tool directly via their package manager. You will still need to configure your license key prior to usage.usage-statistics.dbfile
in your local.cfg
configuration file. usage-statistics.dbfile
in your local.cfg
configuration file. 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:
For the time being, you can work around this problem by installing Git locally: https://git-scm.com/downloads
Create a DSpace operating system user (optional) . As noted in the prerequisites above, Tomcat (or Jetty, etc) must run as an operating system user account that has full read/write access to the DSpace installation directory (i.e. [dspace]
). Either you must ensure the Tomcat owner also owns [dspace]
, OR you can create a new "dspace" user account, and ensure that Tomcat also runs as that account:
useradd -m dspace
dspace-7.0-beta5
) or branch.Zip file. If you downloaded dspace-7.0-beta5.zip do the following:
unzip dspace-7.0-beta5.zip
.gz file. If you downloaded dspace-7.0-beta.tar.gz do the following:
gunzip -c dspace-7.0-beta5.tar.gz | tar -xf -
For ease of reference, we will refer to the location of this unzipped version of the DSpace release as [dspace-source] in the remainder of these instructions. After unpacking the file, the user may wish to change the ownership of the dspace-7.x folder to the "dspace" user. (And you may need to change the group).
Create a dspace
database user (this user can have any name, but we'll assume you name them "dspace"). This is entirely separate from the dspace
operating-system user created above:
createuser --username=postgres --no-superuser --pwprompt dspace
You will be prompted (twice) for a password for the new dspace
user. Then you'll be prompted for the password of the PostgreSQL superuser (postgres
).
Create a dspace
database, owned by the dspace
PostgreSQL user. Similar to the previous step, this can only be done by a "superuser" account in PostgreSQL (e.g. postgres
):
createdb --username=postgres --owner=dspace --encoding=UNICODE dspace
You will be prompted for the password of the PostgreSQL superuser (postgres
).
Finally, you MUST enable the pgcrypto extension on your new dspace database. Again, this can only be enabled by a "superuser" account (e.g. postgres
)
# Login to the database as a superuser, and enable the pgcrypto extension on this database psql --username=postgres dspace -c "CREATE EXTENSION pgcrypto;"
The "CREATE EXTENSION" command should return with no result if it succeeds. If it fails or throws an error, it is likely you are missing the required pgcrypto extension (see Database Prerequisites above).
Alternative method: How to enable pgcrypto via a separate database schema. While the above method of enabling pgcrypto is perfectly fine for the majority of users, there may be some scenarios where a database administrator would prefer to install extensions into a database schema that is separate from the DSpace tables. Developers also may wish to install pgcrypto into a separate schema if they plan to "clean" (recreate) their development database frequently. Keeping extensions in a separate schema from the DSpace tables will ensure developers would NOT have to continually re-enable the extension each time you run a "./dspace database clean
". If you wish to install pgcrypto in a separate schema here's how to do that:
# Login to the database as a superuser psql --username=postgres dspace # Create a new schema in this database named "extensions" (or whatever you want to name it) CREATE SCHEMA extensions; # Enable this extension in this new schema CREATE EXTENSION pgcrypto SCHEMA extensions; # Grant rights to call functions in the extensions schema to your dspace user GRANT USAGE ON SCHEMA extensions TO dspace; # Append "extensions" on the current session's "search_path" (if it doesn't already exist in search_path) # The "search_path" config is the list of schemas that Postgres will use SELECT set_config('search_path',current_setting('search_path') || ',extensions',false) WHERE current_setting('search_path') !~ '(^|,)extensions(,|$)'; # Verify the current session's "search_path" and make sure it's correct SHOW search_path; # Now, update the "dspace" Database to use the same "search_path" (for all future sessions) as we've set for this current session (i.e. via set_config() above) ALTER DATABASE dspace SET search_path FROM CURRENT;
Setting up DSpace to use Oracle is a bit different now. You will need still need to get a copy of the Oracle JDBC driver, but instead of copying it into a lib directory you will need to install it into your local Maven repository. (You'll need to download it first from this location: http://www.oracle.com/technetwork/database/enterprise-edition/jdbc-112010-090769.html.) Run the following command (all on one line):
mvn install:install-file -Dfile=ojdbc6.jar -DgroupId=com.oracle -DartifactId=ojdbc6 -Dversion=11.2.0.4.0 -Dpackaging=jar -DgeneratePom=true
You need to compile DSpace with an Oracle driver (ojdbc6.jar) corresponding to your Oracle version - update the version in [dspace-source]/pom.xml E.g.:
<dependency> <groupId>com.oracle</groupId> <artifactId>ojdbc6</artifactId> <version>11.2.0.4.0</version> </dependency>
NOTE: You will need to ensure the proper db.*
settings are specified in your local.cfg
file (see next step), as the defaults for all of these settings assuming a PostgreSQL database backend.
db.url = jdbc:oracle:thin:@host:port/SID # e.g. db.url = jdbc:oracle:thin:@//localhost:1521/xe # NOTE: in db.url, SID is the SID of your database defined in tnsnames.ora # the default Oracle port is 1521 # You may also use a full SID definition, e.g. # db.url = jdbc:oracle:thin:@(description=(address_list=(address=(protocol=TCP)(host=localhost)(port=1521)))(connect_data=(service_name=DSPACE))) # Oracle driver and dialect db.driver = oracle.jdbc.OracleDriver db.dialect = org.hibernate.dialect.Oracle10gDialect # Specify DB username, password and schema to use db.username = db.password = db.schema = ${db.username} # For Oracle, schema is equivalent to the username of your database account, # so this may be set to ${db.username} in most scenarios
Later, during the Maven build step, don't forget to specify mvn -Ddb.name=oracle package
[dspace-source]/dspace/config/local.cfg
configuration file (you may wish to simply copy the provided [dspace-source]/dspace/config/local.cfg.EXAMPLE
). This local.cfg file can be used to store any configuration changes that you wish to make which are local to your installation (see local.cfg configuration file documentation). ANY setting may be copied into this local.cfg file from the dspace.cfg or any other *.cfg file in order to override the default setting (see note below). For the initial installation of DSpace, there are some key settings you'll likely want to override, those are provided in the [dspace-source]/dspace/config/local.cfg.EXAMPLE
. (NOTE: Settings followed with an asterisk (*) are highly recommended, while all others are optional during initial installation and may be customized at a later time)dspace.dir*
- must be set to the [dspace] (installation) directory (NOTE: On Windows be sure to use forward slashes for the directory path! For example: "C:/dspace
" is a valid path for Windows.)dspace.server.url*
- complete, public URL of this DSpace backend (including port and any subpath). For example: http://localhost:8080/server/dspace.ui.url*
- complete, public URL of the DSpace frontend (including port and any subpath). REQUIRED for the REST API to fully trust requests from the DSpace frontend. For example: http://localhost:4000/dspace.name
- "Proper" name of your server, e.g. "My Digital Library".solr.server
* - complete URL of the Solr server. DSpace makes use of Solr for indexing purposes. http://localhost:8983/solr unless you changed the port or installed Solr on some other host.default.language -
Default language for all metadata values (defaults to "en_US")db.url* -
The full JDBC URL to your database (examples are provided in the local.cfg.EXAMPLE
)
db.driver* -
Which database driver to use, based on whether you are using PostgreSQL or Oracle
db.dialect* -
Which database dialect to use, based on whether you are using PostgreSQL or Oracledb.username
* - the database username used in the previous step.db.password
* - the database password used in the previous step.db.schema
* - the database scheme to use (examples are provided in the local.cfg.EXAMPLE)mail.server
- fully-qualified domain name of your outgoing mail server.mail.from.address
- the "From:" address to put on email sent by DSpace.mail.feedback.recipient
- mailbox for feedback mail.mail.admin
- mailbox for DSpace site administrator.alert.recipient
- mailbox for server errors/alerts (not essential but very useful!)registration.notify
- mailbox for emails when new users register (optional)
Your local.cfg file can override ANY settings from other *.cfg files in DSpace
The provided local.cfg.EXAMPLE
only includes a small subset of the configuration settings available with DSpace. It provides a good starting point for your own local.cfg
file.
However, you should be aware that ANY configuration can now be copied into your local.cfg
to override the default settings. This includes ANY of the settings/configurations in:
[dspace]/config/dspace.cfg
)[dspace]/config/modules/*.cfg
files)[dspace-src]/dspace-server-webapp/src/main/resources/application.properties
)Individual settings may also be commented out or removed in your local.cfg
, in order to re-enable default settings.
See the Configuration Reference section for more details.
DSpace Directory: Create the directory for the DSpace backend installation (i.e. [dspace]
). As root (or a user with appropriate permissions), run:
mkdir [dspace] chown dspace [dspace]
(Assuming the dspace UNIX username.)
Build the Installation Package: As the dspace UNIX user, generate the DSpace installation package.
cd [dspace-source] mvn package
Building with Oracle Database Support
Without any extra arguments, the DSpace installation package is initialized for PostgreSQL. If you want to use Oracle instead, you should build the DSpace installation package as follows: mvn -Ddb.name=oracle package
Install DSpace: As the dspace UNIX user, install DSpace to [dspace]
:
cd [dspace-source]/dspace/target/dspace-installer ant fresh_install
To see a complete list of build targets, run: ant help
The most likely thing to go wrong here is the test of your database connection. See the Installing DSpace (OLD - to be removed)#Common Problems Section below for more details.
Technique A. Tell your Tomcat/Jetty/Resin installation where to find your DSpace web application(s). As an example, in the directory [tomcat]/conf/Catalina/localhost
you could add files similar to the following (but replace [dspace]
with your installation location):
<?xml version='1.0'?> <Context docBase="[dspace]/webapps/server"/>
The name of the file (not including the suffix ".xml") will be the name of the context, so for example server.xml
defines the context at http://host:8080/server
. To define the root context (http://host:8080/
), name that context's file ROOT.xml
. Optionally, you can also choose to install the old, deprecated "rest" webapp if you
cp -R [dspace]/webapps/* [tomcat]/webapps*
(This will copy all the web applications to Tomcat). cp -R [dspace]/webapps/server [tomcat]/webapps*
(This will copy only the Server web application to Tomcat.)To define the root context (http://host:8080/
), name that context's directory ROOT
.
[dspace]/webapps/rest
). It is NOT used by the DSpace frontend. So, most users should skip this step.Copy Solr cores: DSpace installation creates a set of four empty Solr cores already configured. Copy them from [dspace]
/solr to the place where your Solr instance will discover them. Start (or re-start) Solr. For example:
cp -R [dspace]/solr/* [solr]/server/solr/configsets [solr]/bin/solr restart
You can check the status of Solr and your new DSpace cores by using its administrative web interface. Browse to http://localhost:8983/
to see if Solr is running well, then look at the cores by selecting (on the left) Core Admin or using the Core Selector drop list.
Create an Administrator Account: Create an initial administrator account from the command line:
[dspace]/bin/dspace create-administrator
Work in progress (Feedback welcome)
Yarn v1.x is available at https://classic.yarnpkg.com/. It can usually be install via NPM (or through your Linux distribution's package manager)
# You may need to run this command using "sudo" if you don't have proper privileges npm install --global yarn
PM2 is very easily installed via NPM
# You may need to run this command using "sudo" if you don't have proper privileges npm install --global pm2
dspace-7.0-beta5
) or branch.Install all necessary local dependencies by running the following from within the unzipped "dspace-angular" directory
# change directory to our repo cd dspace-angular # install the local dependencies yarn install
Create a Production Configuration file at [dspace-angular]/src/environment/environment.prod.ts
. You may wish to use the environment.template.ts
as a starting point. This environment.prod.ts
file can be used to override any of the default configurations specified in the environment.common.ts (in that same directory). At a minimum this file MUST include the "ui" and "rest" sections similar to the following (keep in mind, you only need to include settings that you need to modify):
export const environment = { // The "ui" section defines where you want Node.js to run/respond. It may correspond to your public URL, but it also may not (if you are running behind a proxy). // In this example, we are setting up our UI to just use localhost port 4000. // This is a common setup for when you want to use Apache or Nginx to handle HTTPS and proxy requests to Node on port 4000 ui: { ssl: false, host: '0.0.0.0', port: 4000, // NOTE: Space is capitalized because 'namespace' is a reserved string in TypeScript nameSpace: '/' } // This example is valid if your Backend is publicly available at https://api.mydspace.edu/server/ // The REST settings MUST correspond to the public URL of the backend. Usually, this means they must be kept in sync // with the value of "dspace.server.url" in the backend's local.cfg rest: { ssl: true, host: 'api.mydspace.edu', port: 443, // NOTE: Space is capitalized because 'namespace' is a reserved string in TypeScript nameSpace: '/server' } };
yarn start
" and trying to access it via http://[mydspace.edu]:4000/
from your web browser. KEEP IN MIND, we highly recommend always using HTTPS for Production.environment.common.ts
configuration file you can also copy them into this same file.Build the User Interface for Production. This uses your environment.prod.ts
and the source code to create a compiled version of the UI in the [dspace-angular]/dist
folder
yarn run build:prod
environment.prod.ts
, then you will need to rebuild the UI application (i.e. rerun this command).Assuming you are using PM2, create a JSON configuration file describing how to run our UI application. This need NOT be in the same directory as the dspace-angular codebase itself (in fact you may want to put the parent directory or another location). Keep in mind the "cwd" setting (on line 5) must be the full path to your [dspace-angular]
folder.
{ "apps": [ { "name": "dspace-angular", "cwd": "/home/dspace/dspace-angular", "script": "yarn", "args": "run serve:ssr", "interpreter": "none" } ] }
Now, start the application using PM2 using the configuration file you created in the previous step
# In this example, we are assuming the config is named "dspace-angular.json" pm2 start dspace-angular.json # To see the logs, you'd run # pm2 logs # To stop it, you'd run # pm2 stop dspace-angular.json
environment.prod.ts
sudo apt install apache2
sudo en2mod proxy; sudo a2enmod proxy_http
Now, setup a new VirtualHost for your site (preferably using HTTPS / port 443) which proxies all requests to PM2 running on port 4000.
<VirtualHost _default_:443> .. setup your host how you want, including log settings... SSLEngine on SSLCertificateFile [full-path-to-PEM-cert] SSLCertificateKeyFile [full-path-to-cert-KEY] # Proxy all HTTPS requests from Apache to PM2 on port 4000 ProxyPass / http://127.0.0.1:4000/ ProxyPassReverse / http://127.0.0.1:4000/ </VirtualHost>
[dspace-angular]/config/ssl/
folder and add a key.pem
and cert.pem
to that folder (they must have those exact names)After a successful installation, you may want to take a closer look at
If you've run into installation problems, you may want to...
If you are seeing a CORS error in your browser, this means that you are accessing the REST API via an "untrusted" client application. To fix this error, you must change your REST API / Backend configuration to trust the application.
dspace.ui.url
. Therefore, you should first verify that your dspace.ui.url
setting (in your local.cfg) exactly matches the public URL of your User Interface (i.e. the URL you see in the browser). This must be an exact match: mode (http vs https), domain, port, and subpath(s) all must match.rest.cors.allowed-origins
configuration. This should be comma-separated list of trusted URLs. If you customize that setting, MAKE SURE TO include "${dspace.ui.url}" in that setting if you wish to continue trusting the UI. Again, keep in mind any URLs added to this setting must be an exact match: mode (http vs https), domain, port, and subpath(s) all must match.. So, for example, these URLs are all considered different applications: "http://mydspace.edu", "http://mydspace.edu:4000" (different port), "https://mydspace.edu" (http vs https), "https://myapp.mydspace.edu" (different domain), and "https://mydspace.edu/myapp" (different subpath).If you modify either of the above settings, you will need to restart Tomcat for the changes to take effect.
First, double check that you are seeing that exact message. 403 Forbidden can be thrown in a variety of scenarios...it could be page that requires a login, you could have entered an invalid username or password, or you could even be seeing a CORS error (see previous issue for how to solve that).
If you are seeing the message "Invalid CSRF Token" message (especially on every login), this is usually the result of a configuration / installation issue.
Here's some things you should double check:
DSPACE-XSRF-COOKIE
cookie with a value of SameSite=Lax
. This setting means that the cookie will not be sent (by your browser) to any other domains. Effectively, this will block all logins from any domain that is not the same as the REST API (as this cookie will not be sent back to the REST API as required for CSRF validation). In other words, running the REST API on HTTP is only possible if the User Interface is running on the exact same domain. For example, running both on 'localhost' with HTTP is a common development setup, and this will work fine.DSPACE-XSRF-COOKIE
cookie being set to SameSite=None; Secure
. This setting means the cookie will be sent cross domain, but only for HTTPS requests. It also allows the user interface (or other client applications) to be on any domain, provided that the domain is trusted by CORS (see rest.cors.allowed-origins
setting)dspace.server.url
" configuration on the Backend. This simply ensures your UI is sending requests to the correct REST API. Also pay close attention that both specify HTTPS (see previous bullet).dspace.ui.url
" configuration on the Backend matches the public URL of your User Interface (i.e. the URL you see in the browser). This must be an exact match: mode (http vs https), domain, port, and subpath(s) all must match.