Upgrading from DSpace 5.
5
to DSpace 6.2 Using XMLUI
Nason Bimbe
September 2017
Important!
Always consult the official DSpace documentation on installation. Please see
https://wiki.duraspace.org/display/DSDOC6x/Upgrading+DSpace
Introduction
These instructions are based on upgrading from DSpace 5.x to DSpace 6.x on
Ubuntu Server 16.04 LTS.
Prerequisites
DSpace 6.x has the following software prerequisites for all platforms:
• Java JDK v7
• Apache Maven 3.0.5 or later (Java build tool)
o 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.
• Apache Ant 1.8 or later
o Apache Ant is required for the second stage of the build process. It is used
once the installation package has been constructed in [dspace-
source]/dspace/target/dspace-installer and still uses some of the
familiar ant build targets found in the 1.4.x build process.
• PostgreSQL 9.0 or later
• Apache Tomcat 7 or later
• Perl 5
o Only required for [dspace]/bin/dspace-info.pl
Page 1 of 8
Upgrading Process
Update the server
First, ensure that the system is up to date:
sudo apt-get update
sudo apt-get upgrade
Backup your Dspace
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.
Make a complete backup of your system, including:
• Database: Make a snapshot/dump of the database. For the PostgreSQL
database use Postgres' pg_dump command. For example:
pg_dump -U [database-user] -f [backup-file-location]
[database-name]
• Assetstore: Backup the directory ([dspace]/assetstore by default, and
any other assetstores configured in the [dspace]/config/dspace.cfg
"assetstore.dir" and "assetstore.dir.#" settings)
• Configuration: Backup the entire directory content of [dspace]/config.
• Customizations: If you have custom code, such as themes,
modifications, or custom scripts, you will want to back them up to a
safe location.
• Statistics data: what to back up depends on what you were using
before: the options are the default SOLR Statistics, deprecated
Elasticsearch Usage Statistics, or the legacy statistics. Legacy stats
utilizes the dspace.log files, Elasticsearch stats stores data in
[dspace]/elasticsearch, SOLR Statistics stores data in
[dspace]/solr/statistics. A simple copy of the data directory should give
you a point of recovery, should something go wrong in the update
process. It cannot be stressed enough; your users depend on these
statistics more than you realize. You need a backup.
DSpace 6.x requires the following versions of prerequisite software:
• Java 7 or 8 (Oracle or OpenJDK)
• Apache Maven 3.0.5 or above
• Apache Ant 1.8 or above
• Database
o PostgreSQL 9.4 or above (with pgcrypto installed)
Page 2 of 8
• Tomcat 7 or above (Please note that Tomcat 8.0.26 that comes with
Ubuntu 16.04 LTS has problems with DSpace1, try to manual install
the highest stable version. see instructions at
https://www.digitalocean.com/community/tutorials/how-to-install-
apache-tomcat-8-on-ubuntu-16-04)
Setting up DSpace
Download DSpace software
DSpace can be downloaded from GitHub
(https://github.com/DSpace/DSpace/releases). We will be using the source
release, so copy the distribution file to the installation directory /home, for
example and unpack it:
cd $home
wget https://github.com/DSpace/DSpace/releases/download/dspace-
6.x/dspace-6.x-src-release.tar.gz
tar -zxf dspace-6.x-src-release.tar.gz
This will create a directory called dspace-<version>-src-release where
<version> is the number of the DSpace version downloaded. Following the
convention of the DSpace manual, we will refer to this directory as [dspace-
source] in the reminder of this document.
Change the ownership of this directory to the dspace user:
chown -R dspace:dspace dspace-6.x-src-release
Configure PostgreSQL for DSpace 6.x
Enable the pgcrypto extension on your dspace database. Again, this can only
be enabled by a "superuser" account (e.g. postgres)
# Login to the database as a superuser, and enable the pgcrypto
extension on this database
psql --username=postgres dspace -c "CREATE EXTENSION pgcrypto;"
You may get the following Error:
1
https://jira.duraspace.org/browse/DS-3242 and https://groups.google.com/forum/#!topic/dspace-
tech/6NXdCnfRbKo
Page 3 of 8
psql: FATAL: no pg_hba.conf entry for host "[local]", user "postgres",
database "dspace", SSL off
exit
Edit postgreSQL configuration file
/etc/postgresql/<version>/main/pg_hba.conf:
sudo nano /etc/postgresql/<version>/main/pg_hba.conf
Then add this line (make sure the database is not accessible from outside if
possible):
local all all trust
Restart postgresql:
sudo service postgresql restart
Try enabling the pgcrypto extension on your dspace database:
psql --username=postgres dspace -c "CREATE EXTENSION pgcrypto;"
Edit postgreSQL configuration file
/etc/postgresql/<version>/main/pg_hba.conf again:
sudo nano /etc/postgresql/<version>/main/pg_hba.conf
Comment out the line you just added:
#local all all trust
Restart postgresql:
sudo service postgresql restart
Configure DSpace
Initial Configuration (local.cfg): Create your own [dspace-
source]/dspace/config/local.cfg configuration file (you may wish to simply
copy the provided [dspace-source]/dspace/config/local.cfg.EXAMPLE). This
local.cfg file can be used to store any configuration changes that you wish to
Page 4 of 8
make which are local to your installation (see local.cfg configuration
file documentation). ANY setting may be copied into this local.cfg file from
the dspace.cfg or any other *.cfg file to override the default setting (see note
below). For the initial installation of DSpace, there are some key settings
you'll likely want to override, those are provided in the [dspace-
source]/dspace/config/local.cfg.EXAMPLE. (NOTE: Settings followed with an
asterisk (*) are highly recommended, while all others are optional during
initial installation and may be customized later)
cp [dspace-source]/config/dspace/local.cfg.EXAMPLE [dspace-
source]/config/dspace/local.cfg
nano [dspace-source]/config/dspace/local.cfg
Copy the required settings from build.properties and dspace.cfg in your old
DSpace 5.x.
• dspace.dir* - must be set to the [dspace] (installation)
directory (NOTE: 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 (or
"localhost" if you just want to run DSpace locally for now)
• dspace.baseUrl* - complete URL of this server's DSpace home page
(including port), but without any context eg. /xmlui, /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 for indexing purposes.
• default.language - Default language for all metadata values
(defaults to "en_US")
• db.url* - The full JDBC URL to your database (examples are provided
in the local.cfg.EXAMPLE)
• db.driver* - Which database driver to use, based on whether you are
using PostgreSQL or Oracle
• db.dialect* - Which database dialect to use, based on whether you
are using PostgreSQL or Oracle
• db.username* - the database username used in the previous step.
• db.password* - the database password used in the previous step.
• db.schema* - the database scheme to use (examples are provided in
the local.cfg.EXAMPLE)
• 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.
Page 5 of 8
• mail.alert.recipient - mailbox for server errors/alerts (not
essential but very useful!)
• mail.registration.notify- mailbox for emails when new users
register (optional)
Others may be (as per your enhancements):
##################################
# LOCAL MODS [Examples #
##################################
# show number of items in community, collection
webui.strengths.show = true
# add language switching for UI, in this case we have allowed
English, French, Portuguese and Arabic
webui.supported.locales = en, fr, pt, ar
# display thumbnails in browse and search result pages
webui.browse.thumbnail.show = true
# display thumbnail against each bitstream in item display
webui.item.thumbnail.show = true
# display thumbnail against each bitstream in item preview
webui.preview.enabled = true
# display thumbnail on Latest Additions listing. The default
value for this is metadata, so change it to file
xmlui.theme.mirage.item-list.emphasis = file
# Item Preview
webui.preview.brand = [Name of your institution]
webui.preview.brand.abbrev = [Abbrev. Name of your institution]
# RSS settings
webui.feed.items=10
harvest.includerestricted.rss=false
harvest.includerestricted.oai=false
harvest.includerestricted.subscription=false
# Google Analytics key
xmlui.google.analytics.key=
# Extra search fields
search.index.13 = issuedate:dc.date.issued
search.index.14 = accessioneddate:dc.date.accessioned:timestamp
search.index.15 = rights:dc.rights.uri
search.index.16 = dctype:dc.type
Page 6 of 8
# maximum width and height of generated thumbnails
thumbnail.maxwidth = 160
thumbnail.maxheight = 160
Update all the other configuration settings that you may have customized,
such as: -
• Email Messages
• Other module configuration settings
• Crosswalks
• etc.
Merge any User Interface customizations or other customizations (if
needed or desired). If you have made any local customizations to your
DSpace installation they may need to be migrated over to the new DSpace.
• NOTE: If you are upgrading across many versions of DSpace at once
(e.g. from 1.x.x to 6.x), you may find it easier to first upgrade
DSpace, and then attempt to migrate over your various
customizations. Because each major version of DSpace tends to add
new configurations and features to the User Interface, older
customizations may require more work to "migrate" to the latest
version of DSpace. In some situations, it may even be easier to "start
fresh", and just re-customize the brand-new User Interface with your
local color scheme, header/footer, etc.
• Customizations are typically housed in one of the following places:
o XMLUI modifications: [dspace-
source]/dspace/modules/xmlui/src/main/webapp/
o Config modifications: [dspace]/config
Build and update DSpace
We will build DSpace with the responsive user interface Mirage2.
Enable Mirage2 responsive UI
Install git if not yet installed
sudo apt-get install git
Just in case force git to use port 443:
git config –-global url.”https://”.insteadOf git://
Modify xmlui.xconf in [dspace-source]/dspace/config with the following: -
<!-- Mirage theme, @mire contributed theme, default since
DSpace 3.0 -->
Page 7 of 8
<!--<theme name="Atmire Mirage Theme" regex=".*"
path="Mirage/" />-->
<!-- Mirage2 theme, @mire contributed theme -->
<theme name="Atmire Mirage2 Theme" regex=".*"
path="Mirage2/" />
Run the Maven package for DSpace as the dspace user:
cd [dspace-source]
mvn -U clean package -Dmirage2.on=true
This may download many additional packages in order to generate the
Dspace installation.
Next, run the Ant build (still logged in as dspace user):
cd [dspace-source]/dspace/target/dspace-installer
Update deployment
ant update
restart tomcat:
sudo systemctl restart tomcat
Initialise the DSpace database (optional)
- While this step is optional (as the DSpace database will auto-initialize itself
on first startup), it's always good to verify one last time that your database
connection is working properly. To initialize the database run (logged in as
dspace user) but first stop Tomcat:
[dspace]/bin/dspace database migrate
Sources
DSpace 6.x Documentation –
https://wiki.duraspace.org/display/DSDOC6x/Upgrading+DSpace
Page 8 of 8
