Page History
...
Note | ||
---|---|---|
| ||
These installation instructions are a work-in-progress and based heavily on the DSpace 6.x installation instructions. Feedback or improvements are welcome. |
Backend Requirements
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. 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 |
UNIX-like OS or Microsoft Windows
- UNIX-like operating system (Linux, HP/UX, Mac OSX, etc.) : Many distributions of Linux/Unix come with some of the dependencies below pre-installed or easily installed via updates. You should consult your particular distribution's documentation or local system administrators to determine what is already available.
- Microsoft Windows: While DSpace can be run on Windows servers, most institutions tend to run it on a UNIX-like operating system.
Java JDK 11 (OpenJDK or Oracle JDK)
- 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).
- Oracle's Java can be downloaded from the following location: http://www.oracle.com/technetwork/java/javase/downloads/index.html. Make sure to download the appropriate version of the Java SE JDK.
Info | ||
---|---|---|
| ||
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. |
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. |
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 Proxy
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:
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 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 ([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
Relational Database (PostgreSQL or Oracle)
PostgreSQL v11 (with pgcrypto installed)
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 can be downloaded from http://www.postgresql.org/. It is also provided via many operating system package managers
- If the version of Postgres provided by your package manager is outdated, you may wish to use one of the official PostgreSQL provided repositories:
- Linux users can select their OS of choice for detailed instructions on using the official PostgreSQL apt or yum repository: http://www.postgresql.org/download/linux/
- Windows users will need to use the windows installer: http://www.postgresql.org/download/windows/
- Mac OSX users can choose their preferred installation method: http://www.postgresql.org/download/macosx/
- If the version of Postgres provided by your package manager is outdated, you may wish to use one of the official PostgreSQL provided repositories:
- Install the pgcrypto extension. It will also need to be enabled on your DSpace Database (see Installation instructions below for more info). The pgcrypto extension allows DSpace to create UUIDs (universally unique identifiers) for all objects in DSpace, which means that (internal) object identifiers are now globally unique and no longer tied to database sequences.
- On most Linux operating systems (Ubuntu, Debian, RedHat), this extension is provided in the "postgresql-contrib" package in your package manager. So, ensure you've installed "postgresql-contrib".
- On Windows, this extension should be provided automatically by the installer (check your "[PostgreSQL]/share/extension" folder for files starting with "pgcrypto")
- Unicode (specifically UTF-8) support must be enabled (but this is enabled by default).
- Once installed, you need to enable TCP/IP connections (DSpace uses JDBC):
- In
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.- Then restart PostgreSQL.
- In
Oracle 10g or later
- Details on acquiring Oracle can be downloaded from the following location: http://www.oracle.com/database/. You will need to create a database for DSpace. Make sure that the character set is one of the Unicode character sets. DSpace uses UTF-8 natively, and it is suggested that the Oracle database use the same character set. You will also need to create a user account for DSpace (e.g. dspace) and ensure that it has permissions to add and remove tables in the database. Refer to the Quick Installation for more details.
- NOTE: If the database server is not on the same machine as DSpace, you must install the Oracle client to the DSpace server and point
tnsnames.ora
andlistener.ora
files to the database the Oracle server.
- NOTE: If the database server is not on the same machine as DSpace, you must install the Oracle client to the DSpace server and point
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 /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.
Git (code version control)
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
Installing the Frontend (User Interface)
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. |
Frontend Requirements
UNIX-like OS or Microsoft Windows
- UNIX-like OS operating system (Linux, HP/UX, Mac OSX, etc.) : Many distributions of Linux/Unix come with some of the dependencies below pre-installed or easily installed via updates. You should consult your particular distribution's documentation or local system administrators to determine what is already available.
- Microsoft Windows: While DSpace can be run on Windows servers, most institutions tend to run it on a UNIX-like OS. However, we've added notesoperating system.
Node.js (v10.x or v12.x)
- Node.js can be found at https://nodejs.org/. We recommend running a Long Term Support (LTS) version (latest is 12.x). Non-LTS versions are not recommended.
- Node.js is a Javascript runtime that also provides npm (Node Package Manager). It is used to both build and run the frontend.
...
- The DSpace Frontend cannot function without an installed DSpace Backend. Follow the instructions above.
- The Frontend and Backend need not be installed on the same server. They may be installed on separate machines as long as the two machines can connect to one another via HTTP or HTTPS.
Frontend Installation
Note | ||
---|---|---|
| ||
At this time, installation requires checking out the codebase via Git. In later Beta releases, we will provide prepackaged downloads. |
...