Contribute to the DSpace Development Fund

The newly established DSpace Development Fund supports the development of new features prioritized by DSpace Governance. For a list of planned features see the fund wiki page.

Introduction

An approach for upgrading from DSpace 1.4.2 (old) to 1.5 to 1.5.2
(new) is described that differs from the steps listed in the
DSpace 1.5.2 Manual. This procedure was applied to a

  • Red Hat 5.3 GNU/Linux platform with
  • PostgresSQL 8.1 and
  • Tomcat 5.5.25.

At the start, DSpace 1.4.2 is already running. At the end, both old and new
DSpace are running. The installation procedure does not interfere with
the old DSpace and allows for a side-by-side comparison before a final
cut-over to the new. The non-interfering aspect is the main difference between this and the
manual's installation procedure. Be aware the Java Virtual Machine
(JVM) associated with Tomcat and these multiple instances of DSpace
may run out of memory if there are too many DSpaces running in
parallel (no more than three is recommended).

To carry-over local settings, you'll need to install DSpace 1.5 to
rebase your local settings in the files and directories of the newer source
code. You'll need to do this again for DSpace 1.5.2. Some
configuration files to rebase are

  • dspace.cfg,
  • dstat.cfg and
  • log4j.xml.

To rebase means to compare old and new files and
directories and to insert the necessary old values in the new. Be
aware DSpace 1.5 has an issue
DS-110, the batch importer
seems unable to perform the replace operation.

Terms

The manual uses terms such as [dspace] and [dspace-source], the following are terms and their meaning:

  • [dspace-backup] location to copy to e.g. /home/dspace/data-backup
  • [dspace-source] location of source code
    • [dspace-src-1-4-2] e.g. /usr/local/src/dspace-src-1-4-2
    • [dspace-src-1-5] e.g. /usr/local/src/dspace-src-1-5
    • [dspace-src-1-5-2] e.g. /usr/local/src/dspace-src-1-52
  • [dspace] location of installation directory e.g. /dspace
    • [dspace-app-1-4-2] e.g. /usr/local/share/apps/dspace-app-1-4-2
    • [dspace-app-1-5] e.g. /usr/local/share/apps/dspace-app-1-5
    • [dspace-app-1-5-2] e.g. /usr/local/share/apps/dspace-app-1-5-2
  • [dspace-db] name of database as listed by psql -l e.g. dspace
    • [dspace-db-1-4-2] e.g. dspace-db-1-4-2
    • [dspace-db-1-5] e.g. dspace-db-1-5
    • [dspace-db-1-5-2] e.g. dspace-db-1-5-2
  • [other-apps] location of apache-maven & apache-ant dependencies e.g. /usr/local/share/apps

Going from DSpace 1.4.2 to 1.5

16 alternative steps to the DSpace Manual 1.5.2 for 1.4.2 to 1.5 upgrade

step

description

1

backup the system: database, assetstore, [dspace]/config, [dspace]/bin

 ###
 # to backup the database
 ###
 pg_dump [dspace-db] > [dspace-backup]/pg-dump-[dspace-db].sql

 ###
 # to backup the assetstore 
 ###
 # if your assetstore is too big, use your system's regular backup ability
 cp -a [dspace]/assetstore [dspace-backup]/

 ###
 # to backup the DSpace config and bin directories
 ###
 cp -a [dspace]/bin [dspace-backup]/
 cp -a [dspace]/config [dspace-backup]/

 ###
 # to backup the whole system use your regular backup ability
 ###

2

get the source code

 ###
 # for DSpace 1.5
 ###
 mkdir -p [dspace-src-1-5]
 cd [dspace-src-1-5]
 svn checkout http://scm.dspace.org/svn/repo/dspace/tags/dspace-1_5/ .

3

prepare the build environment

 ###
 # to set java environment, use in /home/dspace/.bash_profile
 ###
 export JAVA_HOME='/usr/lib/jvm/java'
 export JRE_HOME="/usr/lib/jvm/jre"
 export JAVA_OPTS="-Xmx1G -Xms64m -Dfile.encoding=UTF-8"

 ###
 # to install apache-maven, get from http://maven.apache.org/
 ###
 cd [other-apps]
 # download, verify and unpack, e.g. apache-maven-2.2.1
 ln -s apache-maven-2.2.1 apache-maven
 cd /home/dspace/bin
 ln -s [other-apps]/apache-maven/bin/mvn mvn
 # to confirm availability
 mvn -h

 ###
 # to install proxy settings for apache-maven, use /home/dspace/.m2/settings.xml
 ###
 <settings>
 <proxies>
 <proxy>
 <active>true</active>
 <protocol>http</protocol>
 <host>[your_proxy_server]</host>
 <port>[port_number]</port>
 </proxy>
 </proxies>
 </settings>

 ###
 # to install apache-ant, get from http://ant.apache.org/
 ###
 cd [other-apps]
 # download, verify and unpack, e.g. apache-ant-1.7.1
 ln -s apache-ant-1.7.1 apache-ant
 cd /home/dspace/bin
 ln -s [other-apps]/apache-ant/bin/ant ant
 # to confirm availability
 ant -h

4

do nothing: there is no need to stop apache-tomcat

5

rebase local settings, build and install DSpace: after the ant fresh_install step; notice how the database is dropped, re-created, re-populated and the database schema updated

 ###
 # for DSpace 1.5, compare and keep old values
 ###
 diff -u [dspace-src-1-4-2]/config/dspace.cfg [dspace-src-1-5]/config/dspace.cfg > /var/tmp/dspace-cfg-1-5-diff
 diff -u [dspace-src-1-4-2]/config/dstat.cfg [dspace-src-1-5]/config/dstat.cfg > /var/tmp/dstat-cfg-1-5-diff
 diff -u [dspace-src-1-4-2]/config/log4j.xml [dspace-src-1-5]/config/log4j.xml > /var/tmp/log4j-xml-1-5-diff

 ###
 # for dspace.cfg for 1.5, use
 ###
 dspace.dir = [dspace-app-1-5]
 dspace.url = http://[fqdn.for.host]:8080/dspace-app-1-5/xmlui
 db.url = jdbc:postgresql://localhost:5432/dspace-db-1-5
 db.password = keep_going

 ###
 # for dstat.cfg for 1.5, use values from [dspace-app-1-4-2]/bin/stat-initial
 ###
 start.year = [as appropriate]
 start.month = [as appropriate]

 ###
 # for log4j.xml for 1.5, use e.g. 20 x 1GiB log files
 ###
 log4j.appender.A1.MaxFileSize=1073741824
 log4j.appender.A1.MaxBackupIndex=20

 ###
 # to create the database in the dspace user context
 ###
 createdb -U dspace -E UNICODE dspace-db-1-5 --password

 ###
 # to build, install and re-init 1.5 (the procedure is similar for 1.5.2)
 ###

 # to create install directory
 mkdir -p [dspace-app-1-5]

 ###
 # go to source code, build using apache-maven
 ###
 cd [dspace-src-1-5]/dspace
 mvn package

 ###
 # to allow access to the database, update /var/lib/pgsql/data/pg_hba.conf
 ###
 host    all         all         127.0.0.1/32          trust

 ###
 # NOTE: see the PostgreSQL manual for setting pg_hba.conf and security implications
 ###

 ###
 # from the target build directory, install using apache-ant
 ###
 cd target/dspace-1.5-build.dir
 ant fresh_install

 ###
 # to re-fill database with old content
 ###
 dropdb dspace-db-1-5
 createdb -U dspace -E UNICODE dspace-db-1-5 --password
 sudo su - postgres -c psql -f [dspace-backup]/pg-dump-[dspace-db].sql dspace-db-1-5
 psql -f [dspace-src-1-5]/dspace/etc/database_schema_14-15.sql dspace-db-1-5

 ###
 # to point link to the assetstore from [dspace-app-1-5] 
 ###
 cd [dspace-app-1-5]
 mv assetstore assetstore.blank
 ln -s [dspace-app-1-4-2]/assetstore assetstore

6to9

do nothing: the rebased local settings should have newer extra config files

10

update the database schema: as done at the end of step 5

 psql -f [dspace-src-1-5]/dspace/etc/database_schema_14-15.sql dspace-db-1-5

11to12

do nothing:

13

rebuild the browse & search index: an assetstore of 100GiB may take 2 hours to complete

 [dspace-app-1-5]/bin/index-init

14

do nothing: see step 5's dstat.cfg

15

deploy web applications: after the following file is in location, you should be able to access

 
 ###
 # in /etc/tomcat5/Catalina/localhost/dspace-app-1-5.xml
 ###
 <?xml version="1.0" encoding="UTF-8"?>
 <Context docBase="/usr/local/share/apps/dspace-app-1-5/webapps/xmlui"
         privileged="true" antiResourceLocking="false" antiJARLocking="false">
  <!-- Link to the user database we will get roles from -->
  <!--
  <ResourceLink name="users" global="UserDatabase"
                type="org.apache.catalina.UserDatabase"/>
                -->
 </Context>

|

16

do nothing: there is no need to interfere with apache-tomcat and old DSpace

Going from DSpace 1.4.2 to 1.5.2

8 alternative steps to the DSpace Manual 1.5.2 for 1.5 to 1.5.2 upgrade

step

description

1

backup the system and data: see step 1 above

2

get the source code: see step 2 above

 ###
 # for DSpace 1.5.2
 ###
 mkdir -p [dspace-src-1-5-2]
 cd [dspace-src-1-5-2]
 svn checkout http://scm.dspace.org/svn/repo/dspace/tags/dspace-1.5.2/ .

3

prepare the build environment: see step 3 above

4

do nothing: there is no need to stop apache-tomcat

5

apply any customizations: and rebase local settings to newer source code files & directories, see above section's step 5 on the use of diff; after the ant fresh_install step; notice how the database is dropped, re-created, re-populated and the database schema updated

 ###
 # for DSpace 1.5.2
 ###
 diff -u [dspace-src-1-5]/config/dspace.cfg [dspace-src-1-5-2]/config/dspace.cfg > /var/tmp/dspace-cfg-1-5-2-diff
 diff -u [dspace-src-1-5]/config/dstat.cfg [dspace-src-1-5-2]/config/dstat.cfg > /var/tmp/dstat-cfg-1-5-2-diff
 diff -u [dspace-src-1-5]/config/log4j.xml [dspace-src-1-5-2]/config/log4j.xml > /var/tmp/log4j-xml-1-5-2-diff

 ###
 # put local settings from old config files as needed in new config files and directories
 ###

 ###
 # for dspace.cfg for 1.5.2, use
 ###
 dspace.dir = [dspace-app-1-5-2]
 dspace.url = http://[fqdn.for.host]:8080/dspace-app-1-5-2/xmlui
 db.url = jdbc:postgresql://localhost:5432/dspace-db-1-5-2
 db.password = keep_going

 ###
 # to create the databases in the dspace user context
 ###
 createdb -U dspace -E UNICODE dspace-db-1-5-2 --password

 ###
 # to build, install and re-init 1.5.2
 ###

 # to create install directory
 mkdir -p [dspace-app-1-5-2]

 ###
 # go to source code, build using apache-maven
 ###
 cd [dspace-src-1-5-2]/dspace
 mvn package

 ###
 # from the target build directory, install using apache-ant
 ###
 cd target/dspace-1.5.2-build.dir
 ant fresh_install

 ###
 # to re-fill database with old content
 ###
 dropdb dspace-db-1-5-2
 createdb -U dspace -E UNICODE dspace-db-1-5-2 --password
 sudo su - postgres -c psql -f [dspace-backup]/pg-dump-[dspace-db].sql dspace-db-1-5-2
 psql -f [dspace-src-1-5-2]/dspace/etc/database_schema_14-15.sql dspace-db-1-5-2

 ###
 # to point link to the assetstore from [dspace-app-1-5-2] 
 ###
 cd [dspace-app-1-5-2]
 mv assetstore assetstore.blank
 ln -s [dspace-app-1-4-2]/assetstore assetstore

 ###
 # rebuild the browse and search index which may take 2 hours for 100 GiB
 ###
 [dspace-src-1-5-2]/bin/index-init

 ###
 # NOTE: to permanently go to 1.5.2, move the assetore from 1.4.2 to 1.5.2 (update links elsewhere if needed)
 ###
 cd [dspace-1-5-2]
 mv assetstore assetstore.link
 mv [dspace-1-4-2]/assetstore [dspace-1-5-2]/

6to7

*do nothing:*rebase local settings in newer source code files & directories

8

deploy web application: there is no need to start apache-tomcat as it was not stopped in step 4; after the following file is in location, you should be able to access

 
 ###
 # in /etc/tomcat5/Catalina/localhost/dspace-app-1-5-2.xml
 ###
 <?xml version="1.0" encoding="UTF-8"?>
 <Context docBase="/usr/local/share/apps/dspace-app-1-5-2/webapps/xmlui"
         privileged="true" antiResourceLocking="false" antiJARLocking="false">
  <!-- Link to the user database we will get roles from -->
  <!--
  <ResourceLink name="users" global="UserDatabase"
                type="org.apache.catalina.UserDatabase"/>
                -->
 </Context>

|

  • No labels

All content on the LYRASIS Wiki is licensed under the CC BY (Attribution) license, unless otherwise noted.