Page History

...

1. Backup Your DSpace. First, and foremost, make a complete backup of your system, including:
   • A snapshot of the database. To have a "snapshot" of the PostgreSQL database, you need to shut it down during the backup. You should also have your regular PostgreSQL Backup output (using pg_dump commands).

   • Wiki Markup
     The asset store (_\[dspace\]/assetstore_ by default)

   • Your configuration files and customizations to DSpace (including any customized scripts).
2. Download DSpace 1.6.1 Retrieve the new DSpace 1.6.2 source code either as a download from DSpace.org or check it out directly from the SVN code repository. If you downloaded DSpace do not unpack it on top of your existing installation. Refer to Chapter 3.3.3 Installation, Step 3 for unpacking directives.
3. Stop Tomcat. Take down your servlet container. For Tomcat, use the $CATALINA/shutdown.sh script. (Many installations will have a startup/shutdown script in the /etc/init.d or /etc/rc.d directories.

4. Wiki Markup
   *Apply any customizations.* If you have made any local customizations to your DSpace installation they will need to be migrated over to the new DSpace. These are housed in one of the following places:JSPUI modifications: _\[dspace-source\]/dspace/modules/jspui/src/main/webapp/_XMLUI modifications: \_\[dspace-source\]/dspace/modules/xmlui/src/main/webapp_

5. Update Configuration Files. There are no additions to this release. So you do not have to update the configuration files.
6. Build DSpace. Run the following commands to compile DSpace.:

   Code Block
   cd /[dspace-source]/dspace/ mvn -U clean package

   Wiki Markup
   You will find the result in _\[dspace-source\]/dspace/target/dspace-\[version\]-build.dir_ . Inside this directory is the compiled binary distribution of DSpace. Before rebuilding DSpace, the above command will clean out any previously compiled code ('clean') and ensure that your local DSpace JAR files are updated from the remote maven repository.

7. Update DSpace. Update the DSpace installed directory with the new code and libraries. Issue the following commands:

   Code Block
   cd [dspace-source]/dspace/target/dspace-[version]-build.dir ant -Dconfig=[dspace]/config/dspace.cfg update

8. Wiki Markup

   *Run Registry Format Update for CC License.* Creative Commons licenses have been assigned the wrong mime-type in past versions of DSpace. Even if you are not currently using CC Licenses, you should update your Bitstream Format Registry to include a new entry with the proper mime-type. To update your registry, run the following command: _dspace\]/bin/dspace registry-loader \-bitstream \[dspace\]/etc/upgrades/15-16/new-bitstream-formats.xml_

9. Update the Database. If you are using Creative Commons Licenses in your DSpace submission process, you will need to run the 1.5.x to 1.6.x database upgrade script again. In 1.6.0 the improper mime-type was being assigned to all CC Licenses. This has now been resolved, and rerunning the upgrade script will now assign the proper mime-type to all existing CC Licenses in your DSpace installation. NOTE: You will receive messages that most of the script additions already exist. This is normal, and nothing to be worried about.

   • Wiki Markup
     For PostgreSQL: _psql \-U \[dspace-user\] \-f \[dspace-source\]/dspace/etc/postgres/database_schema_15-16.sql \[database name\]_ (Your database name is by default 'dspace'). Example:

     Code Block
     psql -U dspace -f /dspace-1.6-1-src-release/dspace/etc/postgres/database_schema_15-16.sql dspace

     (The line break above is cosmetic. Please place your command in one line.
   • For Oracle: Execute the upgrade script, e.g. with sqlplus, recording the output:

     1. Wiki Markup
        Start SQL*Plus with "_sqlplus \[connect args\]_"

     2. Record the output: SQL> spool 'upgrade.lst'

     3. Wiki Markup
        Run the upgrade script _SQL> @\[dspace-source\]/dspace/etc/oracle/database_schema_15-16.sql{_}{_}SQL> spool off_

     4. Please note: The final few statements WILL FAIL. That is because you have run some queries and use the results to construct the statements to remove the constraints, manually‚ Oracle doesn't have any easy way to automate this (unless you know PL/SQL). So, look for the comment line beginning:

        Code Block
        "--You need to remove the already in place constraints" and follow the instructions in the actual SQL file. Refer to the contents of the spool file "upgrade.lst" for the output of the queries you'll need.

10. Wiki Markup
    *Generate Browse and Search Indexes*. Though there are not any database changes in the 1.6 to 1.6.1 release, it makes good policy to rebuild your search and browse indexes when upgrading to a new release. To do this, run the following command from your DSpace install directory (as the dspace user):_\[dspace\]/bin/dspace index-init_

11. Wiki Markup
    *Deploy Web Applications*. Copy the web applications files from your _\[dspace\]/webapps_ directory to the subdirectory of your servlet container (e.g. tomcat):_cp \-R \[dspace\]/webapps/\* \[tomcat\]/webapps/_

12. Restart servlet. Now restart your Tomcat/Jetty/Resin server program and test out the upgrade.

...

1. Wiki Markup
   Step one is, of course, to *back up all your data* before proceeding\!\! Include all of the contents of {{\[dspace\]}} and the PostgreSQL database in your backup.

2. Get the new DSpace 1.3.x source code from the DSpace page on SourceForge and unpack it somewhere. Do not unpack it on top of your existing installation!!

3. Wiki Markup
   Copy the PostgreSQL driver JAR to the source tree. For example: _cd \[dspace\]/lib{_}{_}cp postgresql.jar \[dspace-1.2.2-source\]/lib_

4. Take down Tomcat (or whichever servlet container you're using).

5. Wiki Markup
   Remove the old version of _xerces.jar_ from your installation, so it is not inadvertently later used:_rm \[dspace\]/lib/xerces.jar_

6. Wiki Markup
   Install the new config files by moving _dstat.cfg_ and _dstat.map_ from _\[dspace-1.3.x-source\]/config/_ to _\[dspace\]/config_

7. Wiki Markup
   You need to add new parameters to your _\[dspace\]/dspace.cfg_:

   Code Block
   ###### Statistical Report Configuration Settings ###### # should the stats be publicly available? should be set to false if you only # want administrators to access the stats, or you do not intend to generate # any report.public = false # directory where live reports are stored report.dir = /dspace/reports/

8. Wiki Markup
   Build and install the updated DSpace 1.3.x code. Go to the _\[dspace-1.3.x-source\]_ directory, and run:_ant \-Dconfig=\[dspace\]/config/dspace.cfg update_

9. Wiki Markup

   You'll need to make some changes to the database schema in your PostgreSQL database. _\[dspace-1.3.x-source\]/etc/database_schema_12-13.sql_ contains the SQL commands to achieve this. If you've modified the schema locally, you may need to check over this and make alterations. To apply the changes, go to the source directory, and run: _psql \-f etc/database_schema_12-13.sql \[DSpace database name\] \-h localhost_

10. Customize the stat generating statistics as per the instructions in System Statistical Reports

11. Wiki Markup
    Initialize the statistics using: _\[dspace\]/bin/stat-initial{_}_\[dspace\]/bin/stat-general{_}_\[dspace\]/bin/stat-report-initial{_}_\[dspace\]/bin/stat-report-general_

12. Wiki Markup
    Rebuild the search indexes: _\[dspace\]/bin/index-all_

13. Wiki Markup
    Copy the _.war_ Web application files in _\[dspace-1.3.x-source\]/build_ to the _webapps_ sub-directory of your servlet container (e.g. Tomcat). e.g.:_cp \[dspace-1.3.x-source\]/build/*.war \[tomcat\]/webapps_

14. Restart Tomcat.

...

1. Wiki Markup
   Step one is, of course, to *back up all your data* before proceeding\!\! Include all of the contents of {{\[dspace\]}} and the PostgreSQL database in your backup.

2. Get the new DSpace 1.2 source code from the DSpace page on SourceForge and unpack it somewhere. Do not unpack it on top of your existing installation!!
3. Copy the required Java libraries that we couldn't include in the bundle to the source tree. For example:

   Code Block
   cd [dspace]/lib cp activation.jar servlet.jar mail.jar [dspace-1.2-source]/lib

4. Stop Tomcat (or other servlet container.)
5. It's a good idea to upgrade all of the various third-party tools that DSpace uses to their latest versions:
   • Java (note that now version 1.4.0 or later is required)
   • Tomcat (Any version after 4.0 will work; symbolic links are no longer an issue)
   • PostgreSQL (don't forget to build/download an updated JDBC driver .jar file! Also, back up the database first.)
   • Ant

6. Wiki Markup
   You need to add the following new parameters to your _\[dspace\]/dspace.cfg_:

   Code Block
   ##### Media Filter settings ##### # maximum width and height of generated thumbnails thumbnail.maxwidth = 80 thumbnail.maxheight = 80

   There are one or two other, optional extra parameters (for controlling the pool of database connections). See the version history for details. If you leave them out, defaults will be used.Also, to avoid future confusion, you might like to remove the following property, which is no longer required:

   Code Block
   config.template.oai-web.xml = [dspace]/oai/WEB-INF/web.xml

7. Wiki Markup

   The layout of the installation directory (i.e. the structure of the contents of {{\[dspace\]}}) has changed somewhat since 1.1.1. First up, your 'localized' JSPs (those in jsp/local) now need to be maintained in the _source_ directory. So make a copy of them now\!Once you've done that, you can remove _\[dspace\]/jsp_ and _\[dspace\]/oai_, these are no longer used. (.war Web application archive files are used instead).Also, if you're using the same version of Tomcat as before, you need to *remove the lines from Tomcat's conf/server.xml file that enable symbolic links for DSpace.* These are the _<Context>_ elements you added to get DSpace 1.1.1 working, looking something like this:

   Code Block
   <Context path="/dspace" docBase="dspace" debug="0" reloadable="true" crossContext="true"> <Resources className="org.apache.naming.resources.FileDirContext" allowLinking="true" /> </Context>

   Be sure to remove the <Context> elements for both the Web UI and the OAI Web applications.
8. Build and install the updated DSpace 1.2 code. Go to the DSpace 1.2 source directory, and run:

   Code Block
   ant -Dconfig= [dspace]/config/dspace.cfg update

9. Copy the new config files in config to your installation, e.g.:

   Code Block
   cp [dspace-1.2-source]/config/news-* [dspace-1.2-source]/config/mediafilter.cfg [dspace-1.2-source]/config/dc2mods.cfg [dspace]/config

10. Wiki Markup
    You'll need to make some changes to the database schema in your PostgreSQL database. _\[dspace-1.2-source\]/etc/database_schema_11-12.sql_ contains the SQL commands to achieve this. If you've modified the schema locally, you may need to check over this and make alterations.To apply the changes, go to the source directory, and run:

    Code Block
    psql -f etc/database_schema_11-12.sql [DSpace database name] -h localhost

11. A tool supplied with the DSpace 1.2 codebase will then update the actual data in the relational database. Run it using:

    Code Block
    [dspace]/bin/dsrun org.dspace.administer.Upgrade11To12

12. Then rebuild the search indexes:

    Code Block
    [dspace]/bin/index-all

13. Wiki Markup
    Delete the existing symlinks from your servlet container's (e.g. Tomcat's) _webapp_ sub-directory.Copy the _.war_ Web application files in _\[dspace-1.2-source\]/build_ to the _webapps_ sub-directory of your servlet container (e.g. Tomcat). e.g.:

    Code Block
    cp [dspace-1.2-source]/build/*.war [tomcat]/webapps

14. Restart Tomcat.
15. To get image thumbnails generated and full-text extracted for indexing automatically, you need to set up a 'cron' job, for example one like this:

    Code Block
    # Run the media filter at 02:00 every day 0 2 * * * [dspace]/bin/filter-media

    You might also wish to run it now to generate thumbnails and index full text for the content already in your system.
16. Note 1: This update process has effectively 'touched' all of your items. Although the dates in the Dublin Core metadata won't have changed (accession date and so forth), the 'last modified' date in the database for each will have been changed. This means the e-mail subscription tool may be confused, thinking that all items in the archive have been deposited that day, and could thus send a rather long email to lots of subscribers. So, it is recommended that you turn off the e-mail subscription feature for the next day, by commenting out the relevant line in DSpace's cron job, and then re-activating it the next day. Say you performed the update on 08-June-2004 (UTC), and your e-mail subscription cron job runs at 4am (UTC). When the subscription tool runs at 4am on 09-June-2004, it will find that everything in the system has a modification date in 08-June-2004, and accordingly send out huge emails. So, immediately after the update, you would edit DSpace's 'crontab' and comment out the /dspace/bin/subs-daily line. Then, after 4am on 09-June-2004 you'd 'un-comment' it out, so that things proceed normally. Of course this means, any real new deposits on 08-June-2004 won't get e-mailed, however if you're updating the system it's likely to be down for some time so this shouldn't be a big problem.
17. Note 2: After consultation with the OAI community, various OAI-PMH changes have occurred:
    • The OAI-PMH identifiers have changed (they're now of the form oai:hostname:handle as opposed to just Handles)
    • The set structure has changed, due to the new sub-communities feature.
    • The default base URL has changed

    • Wiki Markup

      As noted in note 1, every item has been 'touched' and will need re-harvesting. The above means that, if already registered and harvested, you will need to re-register your repository, effectively as a 'new' OAI-PMH data provider. You should also consider posting an announcement to the [OAI implementers e-mail list|http://www.openarchives.org/mailman/listinfo/OAI-implementers|OAI implementers e-mail list] so that harvesters know to update their systems. Also note that your site may, over the next few days, take quite a big hit from OAI-PMH harvesters. The resumption token support should alleviate this a little, but you might want to temporarily whack up the database connection pool parameters in _\[dspace\]/config/dspace.cfg_. See the _dspace.cfg_ distributed with the source code to see what these parameters are and how to use them. (You need to stop and restart Tomcat after changing them.)I realize this is not ideal; for discussion as to the reasons behind this please see relevant posts to the OAI community: [post one|http://openarchives.org/pipermail/oai-implementers/2004-June/001214.html|post one], [post two|http://openarchives.org/pipermail/oai-implementers/2004-June/001224.html|post two], as well as [this post to the dspace-tech mailing list\|#\|this post to the dspace-tech mailing list|].If you really can't live with updating the base URL like this, you can fairly easily have thing proceed more-or-less as they are, by doing the following:

    • Change the value of OAI_ID_PREFIX at the top of the org.dspace.app.oai.DSpaceOAICatalog class to hdl:
    • Change the servlet mapping for the OAIHandler servlet back to / (from /request)
    • Rebuild and deploy _oai.war_However, note that in this case, all the records will be re-harvested by harvesters anyway, so you still need to brace for the associated DB activity; also note that the set spec changes may not be picked up by some harvesters. It's recommended you read the above-linked mailing list posts to understand why the change was made.
      Now, you should be finished!

...