Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents
maxLevel2
typeflat

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
titlename convention
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-cris-master

 

Tip
titlerecommended version

(recommended) Current line of maintenance for 5.x.x:

https://github.com/4Science/DSpace/tree/dspace-5_x_x-cris

 

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.6.1 : https://github.com/4Science/DSpace/tree/dspace-cris-5.6.1

 

DSpace-CRIS Installation Overview (current line of maintenance for 5.x.x)

Info
titleADDONS Integration

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):

 

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

 

You will be prompted for the password of the PostgreSQL superuser (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

 

You will be prompted for the password of the DSpace database user. (This isn't the same as the dspace user's UNIX password.)

3) Initial Configuration:

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
titleORCID integration
ORCID integration, see the last part of build.properties and fill the properties with your need       
Info
titleADDONS Integration

ADDONS integration, see the last part of build.properties and fill the properties with your need     

Info
titleGoogle Maps API policy changed!

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

      Before launch tomcat or deploy war rename webapps to jspui and solr

You copy only (or all) of the DSpace Web application(s) you wish to use from the [dspace]/webapps directory to the appropriate directory in your Tomcat installation. Please note that out-of-box the xmlui webapp is not able to start after to have configured dspace-cris[BA1] . 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).   

      If you use Tomcat 7, recommended, then you have to 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

8) Administrator Account: Create an initial administrator account:

 

Code Block
[dspace]/bin/dspace create-administrator

-----------------------------
Administrator account created
-----------------------------

 

9) 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

The DSpace-CRIS sample configuration

By default, the DSpace-CRIS data configuration is empty.

It is possible to use an excel file to rapidely configure the system, a prefilled excel with common configuration is provided

To load the configuration run the following command two times

 

Code Block
dspace load-cris-configuration -f [dspace]/etc/configuration-tool-demo.xls

 

 

Warning
      The script need to be executed two times as specified in the output

 

Old procedure to load the base configuration (Depracated) - not necessary

For your convenience we provide also a dump of a sample configuration that you can use to explore the system: base-configuration-crismodule.sql:

 

Code Block
dspace database install-example-cris-base

 

or

 

Code Block
psql -h localhost -d dspace -U dspace -f [dspace]/etc/postgres/base-configuration-crismodule.sql

 

This sql file create for you a base metadata configuration for Researcher profile, Organization Unit and Project entity.

You can build or add custom metadata dynamically using the Admin UI, see “The administrative UI”

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.6 

https://github.com/4Science/DSpace/archive/dspace-cris-5.6.1.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
titleupgrade to DSpace-CRIS version prior than 5.6.1

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 13.8 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
titleADDONS TASK!!!

To complete the environment to use addons you take care to run:

Code Block
./dspace registry-loader -metadata ../config/registries/bitstream-types.xml
./dspace registry-loader -metadata ../config/registries/ckan-types.xml
./dspace registry-loader -bitstream ../config/registries/ckan-bitstream-formats.xml

Now you should be able to deploy your webapps, see “Deploy Web Applications” and following steps.