| Warning | ||
|---|---|---|
| ||
This page is outdated. Starting from DSpace-CRIS 7 the technical documentation is available on GitHub as a downloadable PDF in the release version. The current documentation can be downloaded here: DSpace-CRIS7 2023.02.02 Technical Documentation |
| Table of Contents | ||||
|---|---|---|---|---|
|
DSpace-CRIS is an extension of the DSpace platform. This chapter describes how to install DSpace-CRIS from scratch or on the top of an existent DSpace installation.
The source code of the extended version of DSpace can be found in the project’s GitHub Repository.
| Tip | ||
|---|---|---|
| ||
| Current line of development for any DSpace version is maintained in a branch named dspace-<version>-cris, the tagged release dspace-cris-<version> |
Fresh installation
Current line of development for 6.x.x: https://github.com/4Science/DSpace/tree/dspace-6_x_x-cris
| Tip | ||
|---|---|---|
| ||
(recommended) Current line of maintenance for 5.x.x: |
Current line of maintenance for 5.x.x: https://github.com/4Science/DSpace/tree/dspace-5_x_x-cris
Current line of maintenance for 4.x.x: https://github.com/4Science/DSpace/tree/dspace-4_x_x-cris
Tagged releases:
dspace-cris-5.11.0 : https://github.com/4Science/DSpace/releases/tag/dspace-cris-5.11.0
dspace-cris-6.4.0 : https://github.com/4Science/DSpace/releases/tag/dspace-cris-6.4.0
| Info |
|---|
We are committed to keep DSpace-CRIS functionalities aligned in version 5.x and 6.x so that institutions using DSpace-CRIS are not forced to move to the latest version to enjoy all the new functionalities. Please note that DSpace-CRIS 6 is still a release candidate as we are waiting for additional tests before cutting an official release. |
DSpace-CRIS Installation Overview (current line of maintenance for 5.x.x)
| Info | ||
|---|---|---|
| ||
From dspace-cris-5.6.1 DSpace-CRIS coming out with ADDONS feature; To build DSpace-CRIS with an ADDONS you should have the permissions to read from the official repository; By default CKAN-ADDONS is free to use and builded with the usually packaging method. To disable CKAN-ADDONS you MUST add to the mvn package the -P!addon-ckan profile; |
Prerequisite software
See https://wiki.duraspace.org/display/DSDOC5x/Installing+DSpace#InstallingDSpace-PrerequisiteSoftware
0 Create the DSpace user (not necessary).
This needs to be the same user that Tomcat will run as. e.g. as root run:
| Code Block |
|---|
useradd -m usercris |
1) get sources from github repository
4Science organization -- https://github.com/4Science
| Code Block |
|---|
usercris@servercris /e $ mkdir crisinstallation usercris@servercris /e $ cd crisinstallation/ usercris@servercris /e/crisinstallation $ git clone https://github.com/4Science/DSpace.git --branch dspace-5_x_x-cris dspace-parent/ Cloning into 'dspace-parent'... usercris@servercris /e/crisinstallation $ cd dspace-parent/ |
2) Database Setup
PostgreSQL (if you are an Oracle user please contact us, the addon work on Oracle but the installation procedure is actually uncovered in this documentation):
| Info | ||
|---|---|---|
| ||
DSpace-CRIS support Oracle Driver "ojdbc7" with version "12.1.0.2.0" |
A PostgreSQL JDBC driver is configured as part of the default DSpace build. You no longer need to copy any PostgreSQL jars to get PostgreSQL installed.
Create a dspace database user. This is entirely separate from the dspace operating-system user created above.
| Code Block |
|---|
createuser -U postgres -d -A -P dspace |
Depending on how your postgres instance is secured you could be prompted for the password of the PostgreSQL superuser (postgres) or you could require to run the above command using the postgres *nix account (i.e. sudo -u postgres ...). Then you'll be prompted (twice) for a password for the new dspace user.
Create a dspace database, owned by the dspace PostgreSQL user (you are still logged in at 'root'):
| Code Block |
|---|
createdb -U dspace -E UNICODE dspace |
Again, depending on how your postgres instance is secured you could require to switch to a dspace *nix account or force the use of a tcp connection and explicit password authentication for the dspace postgres user (ie. -h 127.0.0.1 -W)
You will need to create the pgcrypto extension in the new dspace database
| Code Block |
|---|
psql -U postgres dspace -c "CREATE EXTENSION pgcrypto;" |
3) Initial Configuration:
| Info | ||
|---|---|---|
| ||
If you are installing a DSpace-CRIS 6 version you will need to edit the [dspace-source]/dspace/config/local.cfg file |
Edit [dspace-source]/build.properties
This properties file contains the basic settings necessary to actually build/install DSpace for the first time (see build.properties Configuration for more detail). In particular you'll need to set these properties, examples or defaults are provided in the file:
dspace.install.dir - must be set to the [dspace] (installation) directory (On Windows be sure to use forward slashes for the directory path! For example: "C:/dspace" is a valid path for Windows.)
dspace.hostname - fully-qualified domain name of web server.
dspace.baseUrl - complete URL of this server's DSpace home page but without any context eg. /jspui, /oai, etc.
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 http://lucene.apache.org/solr/ for indexing purposes.
default.language
db.name - postgres or oracle
db.driver
db.url
db.username - the database password used in the previous step
db.password - the database password used in the previous step.
hibernate.dialect - the sql dialect that use hibernate to speak with database layer
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!)
| Info | ||
|---|---|---|
| ||
| ORCID integration, see the last part of build.properties and fill the properties with your need |
| Info | ||
|---|---|---|
| ||
ADDONS integration, see the last part of build.properties and fill the properties with your need |
| Info | ||
|---|---|---|
| ||
As of June 22, 2016 Google Maps V3 no longer supports keyless access so you need to get a key. Get your key here: https://developers.google.com/maps/documentation/javascript/get-api-key and insert the key into your build.properties. SECURE YOUR API KEY!!! Follow this instruction from Google documentation: "By restricting the IP addresses, referrer URLs, and mobile apps that can use each key, you can reduce the impact of a compromised API key. You can specify the hosts and apps that can use each key from the console by opening the Credentials page and then either creating a new API key with the settings you want, or editing the settings of an API key" Google Maps API homepage: https://developers.google.com/maps/ |
The "build.properties" file is provided as a convenient method of setting only those configurations necessary to install/upgrade DSpace. Any settings changed in this file, will be automatically copied over to the full "dspace.cfg" file (which is held in [dspace-source]/dspace/config/dspace.cfg). Refer to the General Configuration (https://wiki.duraspace.org/display/DSDOC3x/Configuration#Configuration-GeneralConfiguration) section for a fuller explanation.
It is also worth noting that you may choose to copy/rename the "build.properties" under a different name for different environments (e.g. "development.properties", "test.properties", and "production.properties").
You can choose which properties file you want to build DSpace with by passing a "-Denv" (environment) flag to the "mvn package" command (e.g. "mvn package -Denv=test" would build using "test.properties).
See General Configuration (https://wiki.duraspace.org/display/DSDOC3x/Configuration#Configuration-GeneralConfiguration) section for more details.
Do not remove or comment out settings in build.properties When you edit the "build.properties" file (or a custom *.properties file), take care not to remove or comment out any settings. Doing so, may cause your final "dspace.cfg" file to be misconfigured with regards to that particular setting.
Instead, if you wish to remove/disable a particular setting, just clear out its value. For example, if you don't want to be notified of new user registrations, ensure the "mail.registration.notify" setting has no value e.g. mail.registration.notify=
4) DSpace Directory:
Create the directory for the DSpace installation (i.e. [dspace]). As root (or a user with appropriate permissions), run:
| Code Block |
|---|
mkdir [dspace] chown dspace [dspace] |
5) Installation Package:
| Code Block |
|---|
usercris@servercris /e/crisinstallation $ cd dspace-parent/ usercris@servercris /e/crisinstallation/dspace-parent $ mvn package [INFO] Reactor Summary: [INFO] [INFO] DSpace Parent Project .............................. SUCCESS [ 2.002 s] [INFO] DSpace Services Framework :: API and Implementation SUCCESS [ 4.861 s] [INFO] DSpace Kernel :: API and Implementation ............ SUCCESS [ 21.116 s] [INFO] Article Metrics :: Modules ......................... SUCCESS [ 0.089 s] [INFO] Article Metrics :: All ............................. SUCCESS [ 0.111 s] [INFO] Article Metrics :: All :: Retrieve API ............. SUCCESS [ 1.145 s] [INFO] DSpace JSP-UI ...................................... SUCCESS [ 23.078 s] [INFO] DSpace CRIS ........................................ SUCCESS [ 0.057 s] [INFO] DSpace CRIS :: API ................................. SUCCESS [ 4.062 s] [INFO] Article Metrics :: All :: Lookup API ............... SUCCESS [ 0.926 s] [INFO] Article Metrics :: PubMed :: Lookup JSP Web ........ SUCCESS [ 0.269 s] [INFO] DSpace Addon Modules ............................... SUCCESS [ 0.040 s] [INFO] DSpace Kernel :: Additions and Local Customizations SUCCESS [ 0.433 s] [INFO] DSpace XML-UI (Manakin) ............................ SUCCESS [ 25.725 s] [INFO] DSpace CRIS :: Web Application Resources ........... SUCCESS [ 4.680 s] [INFO] DSpace CRIS :: JSPUI API ........................... SUCCESS [ 2.668 s] [INFO] DSpace CRIS :: API ................................. SUCCESS [ 0.049 s] [INFO] CRIS :: WS API ..................................... SUCCESS [ 0.925 s] [INFO] CRIS Webservices Webapp ............................ SUCCESS [ 7.013 s] [INFO] DSpace XML-UI (Manakin) :: Local Customizations .... SUCCESS [ 26.817 s] [INFO] DSpace JSP-UI :: Local Customizations .............. SUCCESS [ 29.536 s] [INFO] DSpace RDF ......................................... SUCCESS [ 9.272 s] [INFO] DSpace RDF :: Local Customizations ................. SUCCESS [ 14.403 s] [INFO] DSpace REST :: API and Implementation .............. SUCCESS [ 13.462 s] [INFO] DSpace REST :: Local Customizations ................ SUCCESS [ 16.839 s] [INFO] DSpace SWORD ....................................... SUCCESS [ 20.902 s] [INFO] DSpace SWORD :: Local Customizations ............... SUCCESS [ 11.823 s] [INFO] DSpace SWORD v2 .................................... SUCCESS [ 11.019 s] [INFO] DSpace SWORD v2 :: Local Customizations ............ SUCCESS [ 11.139 s] [INFO] Apache Solr Webapp ................................. SUCCESS [ 19.772 s] [INFO] DSpace SOLR :: Local Customizations ................ SUCCESS [ 12.307 s] [INFO] DSpace OAI-PMH ..................................... SUCCESS [ 10.873 s] [INFO] DSpace OAI-PMH :: Local Customizations ............. SUCCESS [ 13.926 s] [INFO] DSpace Assembly and Configuration .................. SUCCESS [02:51 min] [INFO] DSpace XML-UI Mirage2 Theme ........................ SUCCESS [ 11.565 s] [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 08:26 min [INFO] Finished at: 2016-01-19T12:09:38+01:00 [INFO] Final Memory: 140M/618M [INFO] ------------------------------------------------------------------------ ----------------------------------------- |
6) Build DSpace and Initialize Database:
As the dspace UNIX user, initialize the DSpace database and install DSpace to [dspace]_:
| Code Block |
|---|
cd [dspace-source]/dspace/target/dspace-installer ant fresh_install ----------------------- BUILD SUCCESSFUL Total time: 49 seconds ----------------------- |
7) Deploy Web Applications
Copy the DSpace Web application(s) you wish to use from the [dspace]/webapps directory to the appropriate directory in your Tomcat installation or create symbolic links from the tomcat/webapps folder to the relevant webapps. Please note that out-of-box also if the xmlui webapp is able to start the CRIS functionalities are available only from the JSPUI . For example:
cp -R [dspace]/webapps/jspui [tomcat]/webapps/ (This will copy only the jspui web application to Tomcat)
cp -R [dspace]/webapps/* [tomcat]/webapps (This will copy all the web applications to Tomcat).
| Warning |
|---|
You need to use Tomcat 7+, and change the startup tomcat script to add a system properties that modify the default Tomcat behavior. So startup tomcat with the follow parameter: -Dorg.apache.el.parser.SKIP_IDENTIFIER_CHECK=true |
| Info |
|---|
| If you want to serve DSpace as the main application for your domain (i.e. having it responding to http://www.mydspace.edu ) you need to copy the jspui webapp in the tomcat webapps folder renaming it to ROOT |
8) Administrator Account: Create an initial administrator account:
| Code Block |
|---|
[dspace]/bin/dspace create-administrator ----------------------------- Administrator account created ----------------------------- |
9) The DSpace-CRIS data model configuration
By default, the DSpace-CRIS data configuration is empty. The initial configuration is provided as an excel file located in
| Code Block |
|---|
[dspace]/etc/configuration-tool-demo.xls |
You should customize this file if you want to make change to the default data model entities and attributes before to proceed. You can add new entities and attributes at any time but you cannot change the type (for example from a string to a date) of already defined attributes from the UI as some manual data check and cleanup will be required.
To load the configuration run the following command two times
| Code Block |
|---|
dspace load-cris-configuration -f [dspace]/etc/configuration-tool-demo.xls |
| Info |
|---|
Since DSpace-CRIS 5.8 the installation and update procedure will automatically load the configuration-tool-demo.xls file to update the data model configuration with improvements and fixes introduced in new version. |
| Warning |
|---|
| The script need to be executed two times as specified in the output. If you start tomcat without loading the data model configuration manually, it will be loaded automatically but as the script need to be executed two times tomcat will automatically exit after the first run and a second tomcat start will be required. |
10) Initial Startup!
Start up (or restart) Tomcat. Visit the base URL(s) of your server.
Base URL of DSpace Web Applications: JSP User Interface - (e.g.) http://localhost:8080/jspui
You should see the DSpace home page. Congratulations! DSpace-CRIS is live! your journey to the world of DSpace-CRIS is just started!
It is time now to setup the appropriate jobs in CRONTAB
Upgrade an existent DSpace-CRIS installation
| Warning |
|---|
Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content.
Before you start your upgrade, it is strongly recommended that you create a backup of your DSpace instance. Backups are easy to recover from; a botched install/upgrade is very difficult if not impossible to recover from. The DSpace specific things to backup are: configs, source code modifications, database, and assetstore. On your server that runs DSpace, you might additionally consider checking on your cron/scheduled tasks, servlet container, and database. |
You can simply update your source code, copy your configuration to the new build.properties and rebuild the system. Flyway will automatically manage the database upgrade in the same way of a standard DSpace migration.
Upgrade an existent DSpace (not CRIS) installation
If you want to apply DSpace-CRIS on top of an existent DSpace Installation you need to perform a slightly different procedure.
This procedure assume that you have a working DSpace installation, any version equal to or less than the DSpace-CRIS version is ok.
| Warning |
|---|
Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content. Backup your content.
Before you start your upgrade, it is strongly recommended that you create a backup of your DSpace instance. Backups are easy to recover from; a botched install/upgrade is very difficult if not impossible to recover from. The DSpace specific things to backup are: configs, source code modifications, database, and assetstore. On your server that runs DSpace, you might additionally consider checking on your cron/scheduled tasks, servlet container, and database. |
You can download the DSpace-CRIS extension based on the official DSpace 5.8
https://github.com/4Science/DSpace/archive/dspace-cris-5.8.0.zip
you are strongly recommended to checkout the 4Science’s DSpace fork from GitHub (5.x.x maintenance), see “1) get sources from github repository”.
https://github.com/4Science/DSpace/archive/dspace-5_x_x-cris.zip
For example:
unzip custom DSpace into folder [path-for-dspace-unzipped]\DSpace-dspace-5_x_x-cris (from here [dspace-src])
After that you have to apply all your changes make in the past from your DSpace to new DSpace-CRIS 5.x
So now you have to build the application from [dspace-src] run the follow command:
mvn -U clean package
6)
| Code Block |
|---|
cd [dspace-source]/dspace/target/dspace-installer ant update |
Create the following folders in the [dspace.dir]:
| Code Block |
|---|
mkdir rp-files mkdir rg-files mkdir ou-files mkdir do-files mkdir ws-xsd cp [dspace-src]/dspace/etc/webservice/* [dspace.dir]/ws-xsd |
7) the procedure is slightly different depending on your current version of DSpace and your migration history.
| Warning | ||
|---|---|---|
| ||
If you are installing a version of DSpace-CRIS older than DSpace-CRIS 5.6.1 you need to always follow the procedure described in the point C below |
There are three different relevant scenarios:
a) upgrade from any version of DSpace < 5.0 or any DSpace 5.x that has never been updated after the initial setup
| Code Block |
|---|
database repair database migrate ignored |
b) a DSpace 5.x coming from a version previous than 3.0 (i.e. 1.2, 1.3, 1.4.x, 1.5.x, 1.6.x, 1.7.x, 1.8.x). You need to apply the same steps described for the scenario A (see above)
c) a DSpace 5.x coming from a previous 3.x or 4.x
Consider a repository that comes out from an old DSpace installation into DSpace 5.x and then to DSpace-CRIS 5.x the workaround is the follow. Running database info and check into column Description of the output the DSpaceCRIS-* label. For each rows marked as State = PreInit, that rows MUST be run manually! In the follow example an user have to migrate from DSpace 3.x to the DSpace 5.x. After working with DSpace 5.x he decide to migrate on DSpace-CRIS 5.x, the output of database info is:
| Code Block |
|---|
+----------------+----------------------------+---------------------+---------+ | Version | Description | Installed on | State | +----------------+----------------------------+---------------------+---------+ | 1.1 | Initial DSpace 1.1 databas | | PreInit | | 1.2 | Upgrade to DSpace 1.2 sche | | PreInit | | 1.3 | Upgrade to DSpace 1.3 sche | | PreInit | | 1.3.9 | Drop constraint for DSpace | | PreInit | | 1.4 | Upgrade to DSpace 1.4 sche | | PreInit | | 1.5 | Upgrade to DSpace 1.5 sche | | PreInit | | 1.5.9 | Drop constraint for DSpace | | PreInit | | 1.6 | Upgrade to DSpace 1.6 sche | | PreInit | | 1.7 | Upgrade to DSpace 1.7 sche | | PreInit | | 1.8 | Upgrade to DSpace 1.8 sche | | PreInit | | 1.8.2.0 | DSpaceCRIS-crismodule data | | PreInit | | 1.8.2.1 | DSpaceCRIS-crispubmed data | | PreInit | | 1.8.2.2 | DSpaceCRIS-subscription da | | PreInit | | 3.0 | Initializing from DSpace 3 | 2015-11-09 15:50:40 | Success | | 3.2.1.0 | DSpaceCRIS-Upgrade-crismod | | Ignored | | 4.0 | Upgrade to DSpace 4.x sche | 2015-11-09 15:50:41 | Success | | 4.1.0.0 | DSpaceCRIS-Upgrade-crismod | | Ignored | | 4.3.0.0 | DSpaceCRIS-Upgrade-crismod | | Ignored | | 5.0.2014.08.08 | DS-1945 Helpdesk Request a | 2015-11-09 15:50:44 | Success | | 5.0.2014.09.25 | DS 1582 Metadata For All O | 2015-11-09 15:50:45 | Success | | 5.0.2014.09.26 | DS-1582 Metadata For All O | 2015-11-09 15:50:45 | Success | | 5.3.0.0 | DSpaceCRIS-Upgrade-crismod | | Pending | | 5.3.0.1 | FIX-SNAPSHOT-DSpaceCRIS-Up | | Pending | | 5.3.0.2 | DSpaceCRIS-Upgrade-crismod | | Pending | | 5.3.0.3 | DSpaceCRIS-Upgrade-crismod | | Pending | | 5.3.0.4 | DSpaceCRIS-Upgrade-crismod | | Pending | | 5.3.0.5 | DSpaceCRIS-Upgrade-crismod | | Pending | | 5.3.0.6 | DSpaceCRIS-Upgrade-crismod | | Pending | | 5.3.1.0 | DSpaceCRIS-Upgrade-crismod | | Pending | | 5.3.1.1 | DSpaceCRIS-Upgrade-crismod | | Pending | | 5.4.0.0 | DSpaceCRIS-Upgrade-crismod | | Pending | | 5.4.0.1 | DSpaceCRIS-Upgrade-crismod | | Pending | | 5.5.0.1 | DSpaceCRIS-Upgrade-crismod | | Pending | | 5.5.1.0 | DSpaceCRIS-Upgrade-crismod | | Pending | | 5.5.1.1 | DSpaceCRIS-Upgrade-crismod | | Pending | | 5.5.1.2 | DSpaceCRIS-Upgrade-crismod | | Pending | +----------------+----------------------------+---------------------+---------+ |
The rows with a PreInit State that are related to DSpace-CRIS MUST be run manually. Run https://github.com/4Science/DSpace/blob/dspace-5_x_x-cris/dspace-api/src/main/resources/org/dspace/storage/rdbms/sqlmigration/postgres/V1.8.2.0__DSpaceCRIS-crismodule_database_schema.sql and https://github.com/4Science/DSpace/blob/dspace-5_x_x-cris/dspace-api/src/main/resources/org/dspace/storage/rdbms/sqlmigration/postgres/V1.8.2.1__DSpaceCRIS-crispubmed_database_schema.sql and https://github.com/4Science/DSpace/blob/dspace-5_x_x-cris/dspace-api/src/main/resources/org/dspace/storage/rdbms/sqlmigration/postgres/V1.8.2.2__DSpaceCRIS-subscription_database_schema.sql
After that, launching database repair and database migrate ignored the migration is complete!
8) Configure ADDONS!!!
| Info | ||
|---|---|---|
| ||
To complete the environment to use addons you take care to run:
|
Now you should be able to deploy your webapps, see “Deploy Web Applications” and following steps.