All Versions
- DSpace 7.x (Current Release)
- DSpace 8.x (Unreleased)
- DSpace 6.x (EOL)
- DSpace 5.x (EOL)
- More Versions...
Table of Contents |
---|
Info | ||
---|---|---|
| ||
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.
Note | ||
---|---|---|
| ||
These installation instructions are a work-in-progress and based heavily on the DSpace 6.x installation instructions. Feedback or improvements are welcome. |
Table of Content Zone | ||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||
UNIX-like OS or Microsoft Windows
Java JDK 11 (OpenJDK or Oracle JDK)
Apache Maven 3.3.x or above (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. Maven can be downloaded from http://maven.apache.org/download.html Configuring a Maven ProxyYou 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:
Apache Ant 1.8 or later (Java build tool)Apache Ant is required for the second stage of the build process (deploying/installing the application). First, Maven is used to construct the installer ( Ant can be downloaded from the following location: http://ant.apache.org Relational Database (PostgreSQL or Oracle)PostgreSQL v11 (with pgcrypto installed)
Oracle 10g or later
Apache Solr 7.2.1 or later (full-text index/search service)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 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. Servlet Engine (Apache Tomcat 8.5 or later, Jetty, Caucho Resin or equivalent)
Git (code version control)Currently, there is a known bug in DSpace where a third-party Maven Module expects
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:
Code Block |
---|
useradd -m dspace |
dspace-7.0-beta2
) or branch.Zip file. If you downloaded dspace-7.0-beta2.zip do the following:
Code Block |
---|
unzip dspace-7.0-beta2.zip |
.gz file. If you downloaded dspace-7.0-beta.tar.gz do the following:
Code Block |
---|
gunzip -c dspace-7.0-beta2.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:
Code Block |
---|
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
):
Code Block |
---|
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
)
Code Block |
---|
# 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:
Code Block |
---|
# 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):
Code Block |
---|
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.:
Code Block | ||
---|---|---|
| ||
<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.
Code Block |
---|
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 URL of this DSpace backend (including port and any subpath). For example: http://localhost:8080/server/dspace.ui.url*
- complete URL of the DSpace frontend (including port and any subpath). 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/ 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.mail.alert.recipient
- mailbox for server errors/alerts (not essential but very useful!)mail.registration.notify
- mailbox for emails when new users register (optional)
Info | ||
---|---|---|
| ||
The provided However, you should be aware that ANY configuration can now be copied into your
Individual settings may also be commented out or removed in your 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:
Code Block |
---|
mkdir [dspace]
chown dspace [dspace] |
(Assuming the dspace UNIX username.)
Build the Installation Package: As the dspace UNIX user, generate the DSpace installation package.
Code Block |
---|
cd [dspace-source]
mvn package
|
Info | ||
---|---|---|
| ||
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: |
Install DSpace: As the dspace UNIX user, install DSpace to [dspace]
:
Code Block |
---|
cd [dspace-source]/dspace/target/dspace-installer
ant fresh_install |
Info |
---|
To see a complete list of build targets, run: |
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):
Code Block | ||
---|---|---|
| ||
<?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
.
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:
Code Block | ||
---|---|---|
| ||
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:
Code Block |
---|
[dspace]/bin/dspace create-administrator |
Note | ||
---|---|---|
| ||
These installation instructions are a work-in-progress. They do NOT yet include production-ready installation scenarios for running the (Angular) frontend via production tools like PM2 or Passenger. Feedback or improvements are welcome. |
Table of Content Zone | ||||
---|---|---|---|---|
| ||||
UNIX-like OS or Microsoft Windows
|
...
|
...
Node.js (v10.x or v12.x)
Yarn (v1.x)
DSpace 7.x Backend (see |
...
above)
|
...
|
Note |
---|
At this time, installation requires checking out the codebase via Git. In later Beta releases, we will provide prepackaged downloads. |
...
|
dspace-7.0-beta2
) or branch.Install all necessary local dependencies by running the following from within the unzipped "dspace-angular" directory
Code Block |
---|
# change directory to our repo
cd dspace-angular
# |
...
install the local dependencies yarn |
...
install |
[dspace-angular]/config/environment.default.js
configuration file, pointing it at your installed DSpace Backend. For example:Code Block |
---|
// This example is valid if your Backend is running at http://localhost:8080/server/
rest: {
ssl: false,
host: 'localhost',
port: 8080,
// NOTE: Space is capitalized because 'namespace' is a reserved string in TypeScript
nameSpace: '/server/api'
} |
Start the application
Code Block |
---|
# build and start the application
yarn start |
After a successful installation, you may want to take a closer look at
If you've run into installation problems, you may want to...
...