About Features Downloads Getting Started Documentation Events Support GitHub

Love VuFind®? Consider becoming a financial supporter. Your support helps build a better VuFind®!

Site Tools


Warning: This page has not been updated in over over a year and may be outdated or deprecated.
installation:migration_notes

This is an old revision of the document!


VuFind Migration Notes

This page provides notes on upgrading to the latest VuFind release from earlier versions.

Notes on upgrading to the latest VuFind 1.x can be found on the legacy migration notes page.

Migrating from VuFind 2.x to the Latest Release

Upgrading from VuFind 2.x or newer is relatively easy, assuming that you isolate all of your changes to the local settings directory, custom module and local theme.

:!: Note that if you have made customizations to your Solr schema or configuration, these changes will need to be reapplied manually.

:!: Always make a backup before upgrading, just to be on the safe side!!

Step-by-Step

Starting with VuFind 2.1, after unpacking the new VuFind, you should follow these steps to be sure your database and configurations are fully updated:

  1. Unpack the new version of VuFind on top of the old version. This will most commonly involve simply downloading the new version, but if you are using Git for version control, it can also be achieved by checking out a different version tag.
  2. Make sure that the config/vufind subdirectory of your local settings directory may be written by the web server and that autoConfigure is turned on in the [System] section of config.ini.
  3. Empty out the cache subdirectory of your local settings directory to be sure no incompatible settings are cached.
  4. Visit http://your-server/vufind/Upgrade/Home to run the automatic upgrade process. You will be prompted to enter the version number of the VuFind release you are upgrading from, and you may be asked to provide root database credentials to update its structure.
  5. Review the auto-upgraded configurations; if necessary, you can restore your previous configurations from backups generated by the upgrade process.
  6. Disable web server write access to the config/vufind subdirectory and turn off autoConfigure in config.ini for security.

:!: It is also strongly recommended that you check the changelog for notes on backward-incompatible changes that might affect e.g. your local customizations.

:!: It is usually a good idea to reindex your records in Solr after an upgrade, assuming you are running a Solr-based VuFind instance.

:!: If you have to maintain a significant number of custom templates, this blog post offers a strategy for automatically updating them with the help of Git.

:!: If you upgrade by reinstalling the DEB package instead of simply unpacking a .zip or .tar.gz archive, be aware that some defaults (particularly in local/httpd-vufind.conf) may be restored. As with other configuration overwriting, backup files should exist that may be easily compared/restored if this causes problems.

Note that Java 1.7 is required starting with VuFind 2.3.

Migrating from VuFind 1.x

Although you have the highest chances of a smooth upgrade process if you migrate from the most recent 1.x release of VuFind, you can skip intermediate steps if you want to – VuFind 2's upgrade process should be able to handle migration from most versions in the 1.x series.

  • Make sure that VuFind 1 is running – the upgrade script will need access to your Solr index.
  • Upgrade Java to 1.7 if needed.
  • Install a copy of VuFind 2 according to the installation notes. Make sure you do not install VuFind 2 into the same directory as VuFind 1. (If you want VuFind 2 to live in the current location of VuFind 1, just move VuFind 1 out of the way prior to installation).
  • Instead of navigating to http://your-server/vufind/Install/Home to configure VuFind, use http://your-server/vufind/Upgrade/Home and follow the on-screen prompts.
  • The automatic upgrade will handle most of your configurations, but several things will require manual attention:
    • Custom code - most code changes can now be isolated to a custom module.
    • Custom themes - 2.0 themes use PHP templates instead of Smarty and have a different directory structure – see customizing the user interface. Note that the smarty2php tool may help automate some of the template upgrading, though it will still require significant manual effort.
    • Solr schema/configuration changes
  • Shut down VuFind 1, reindex your records into VuFind 2, and start VuFind 2's Solr instance.
  • For security, disable web server write access to the config/vufind subdirectory of your local settings directory and turn off autoConfigure in the [System] section of config.ini.

Obviously, it is strongly recommended that you prepare your VuFind 2.0 upgrade on a test server prior to doing this in production – porting old customizations is not a trivial process.

Remember that help is available at the support page if you have questions or problems.

installation/migration_notes.1449865355.txt.gz · Last modified: 2015/12/11 20:22 by demiankatz