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.
name convention
Fresh installation
Current line of development for 6.x.x: https://github.com/Cineca/DSpace/tree/dspace-cris-master
recommended version
(recommended) Current line of maintenance for 5.x.x:
Current line of maintenance for 4.x.x: https://github.com/Cineca/DSpace/tree/dspace-4_x_x-cris
Tagged releases:
- dspace-cris-5.4.0 : https://github.com/Cineca/DSpace/tree/dspace-cris-5.4.0
DSpace-CRIS Installation Overview (current line of maintenance for 5.x.x)
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:
useradd -m usercris
1) get sources from github repository
Cineca organization -- https://github.com/Cineca
usercris@servercris /e $ mkdir crisinstallation usercris@servercris /e $ cd crisinstallation/ usercris@servercris /e/crisinstallation $ git clone https://github.com/Cineca/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.
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'):
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!)
ORCID integration
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:
mkdir [dspace] chown dspace [dspace]
5) Installation Package:
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]_:
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:
[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!
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
dspace load-cris-configuration -f [dspace]/etc/configuration-tool-demo.xls
For your convenience we provide also a dump of a sample configuration that you can use to explore the system: base-configuration-crismodule.sql:
dspace database install-example-cris-base
or
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.
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.4:
https://github.com/Cineca/DSpace/archive/dspace-cris-5.4.0.zip
If you are a developer, you are strongly recommended to checkout the Cineca’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. The database update will be performed automatically when the jspui webapp is deployed and started in your tomcat server by FlyWayDB.
Create the following folders in the [dspace.dir]:
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
Now you should be able to deploy your webapps, see “7) Deploy Web Applications” and following steps.
