Table of Contents
VuFind® Migration Notes
This page provides notes on upgrading to the latest VuFind® release from earlier versions. This process has not changed significantly since release 2.0; notes on upgrading from version 1.x have been removed for clarity, but if you need them, you can click the “Old revisions” button to see earlier versions of this page.
Upgrading from 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
You should follow these steps to be sure your database and configurations are fully updated:
- 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 or merging a different version tag.
- If you are simply downloading the new version rather than using Git, it is safer to delete non-customized files before unpacking, to ensure that obsolete files do not remain as part of your installation.
- If you are installing from Git rather than a downloaded archive, run “composer install” to update dependencies.
- 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.
- Empty out the cache subdirectory of your local settings directory to be sure no incompatible settings are cached.
- 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.
- Review the auto-upgraded configurations; if necessary, you can restore your previous configurations from backups generated by the upgrade process.
- 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 and Solr) may be restored. As with other configuration overwriting, backup files should exist that may be easily compared/restored if this causes problems.
Make sure that your system meets the requirements of the new version.
Special Notes on Upgrading with PostgreSQL
VuFind®'s web-based upgrade script will automatically fix your MySQL database structure for you to account for changes. However, for PostgreSQL, database migrations must be applied manually. Look in the module/VuFind/sql/migrations/pgsql directory to see if there is a migration folder for the new release. If so, the scripts in the migration folder should be applied in numeric order from the command line. You can do this with the command:
psql -U [your-vufind-username] -d [your-vufind-database-name] -a -f [path/to/migration.sql]