Upgrading between EPrints 3.4 versions

This page is intended to provide guidance for those upgrading between versions of EPrints 3.4. (e.g. 3.4.1 to 3.4.2). This is generally intended for those upgrading using source tarballs available on files.eprints.org or upgrading tagged release from EPrints 3.4 GitHub repository. However, if you are upgrading through EPrints Deb or RPM package repostories and you experience issues this page should also contain helpful advice.

General Advice

If you are running EPrints as a virtual machine, then it is worthwhile taking a snapshot that your could revert back to this in the event of an unsuccessful upgrade. Otherwise, you should take the following backups before starting an upgrade:

The EPrints database

This will likely have the same name as the archive.

The documents directory

This is the documents directory, directly under the archive's directory (i.e. <EPRINTS_PATH>/archives/<ARCHIVE_NAME>/).

The Xapian index

This is in the var directory of the archive under the directory named or starting xapian.

Your EPrints archive

All the directories and any files in your archive, except: documents (see above), html and var (except xapian, see above). If you have multiple archives be sure to backup each one.

The current EPrints codebase

In case any changes have been made to this. These may be needed if you have to rollback an upgrade or also apply these changes if they are needed in the upgraded version of EPrints. All directories in the EPrints path (e.g. /opt/eprints3/ or /usr/share/eprints/) should be backed up except: archives (see above), debian, license, pod, testdata, tests,tmp and var. No files in the top level EPrints path directory need to be backed up.

Again, if you have the ability to take a virtual machine snapshot of your EPrints repository, it is worth using this to produce a clone, (if you do not already have a test or pre-production server version of your EPrints repository). This will allow you to check if you will have any snags either with the upgrade process or with the upgraded repository itself. It should also allow you to refine your upgrade schedule for your live EPrint repository to reduce the amount of scheduled downtime required.

Upgrade Schedules

From a source tarball

1. Download the source tarball for the current version of EPrints you have installed from files.eprints.org and unpack in a separate directory on your EPrints repository server. E.g.

tar -xzvf eprints-3.4.1.tar.gz /home/eprints/eprints-3.4.1
tar -xzvf eprints-3.4.1-flavours.tar.gz /home/eprints/eprints-3.4.1

2. Compare the code to see if any changes have been made to the core codebase:

diff -x archives/* -x cfg/* -x ingredients/* -x var/* -rq /opt/eprints3 /home/eprints/eprints-3.4.1

From GitHub release

1. Check that no critical files have been modified in the core codebase.

cd /opt/eprints3/
git status

The only file that should have been modified (assuming you are running a publications flavour of EPrints) is flavours/pub_lib/inc.

There may be various new directories/files under the lib and ingredients directories. These will most likely have been created as a result of installing Bazaar plugins or EPrints ingredients. You should make a note of these and check to see that they are present after the upgrade schedule has been completed.

If there are modified files (according to git status), you should similarly make a note of these and the changes made, so it can be checked if either these changes have already been applied in the upgraded versions of these files or that they need to be re-applied after upgrading.

If git status finds and missing files, then similarly these should be checked to make sure they are not present after completing your upgrade and remove them if they are. They were most likely removed to deliberately disable a piece of unwanted functionality. Although generally it should be possible to disable this with configuration.

2. ...