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-cris-master
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.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 | ||
---|---|---|
| ||
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 | ||
---|---|---|
| ||
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 |
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 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.5:
https://github.com/4Science/DSpace/archive/dspace-cris-5.5.0.zip
If you are a developer, you are strongly recommended to checkout the 4Science’s DSpace fork from GitHub (5.x.x maintenance), see “1) get sources from github repository”.
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
After mvn say build success, you can run "ant update" from [dspace-src]/dspace/target/dspace-[version]-build.dir . The last step is apply all custom folders/files to the [dspace.dir] - refers to the install directory for your existing DSpace installation.
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 |
Migrate the database with the following command:
Code Block |
---|
database repair database migrate ignored |
Note that this kind of command works well only in case of a migration from a version of DSpace 5.x started from scratch.
Info | ||
---|---|---|
| ||
FromNEW!!! fromdspace-cris-5.6.1 DSpace-CRIS manage the automatic database migration old DSpace already migrated to a recently version using Flyway; |
Info | ||
---|---|---|
| ||
MethodOLD methodto manage the migration (pre DSpace-CRIS 5.6)By the way for 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 PreInit, that rows MUST be run manually! In the follow example an user have to migrate from DSpace 1.8 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:
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!
|
Info | ||
---|---|---|
| ||
To complete the environment to use addons you take care to run:
|
Now you should be able to deploy your webapps, see “7) Deploy Web Applications” and following steps.