This page should be used to suggest best practices for moving from one version of VuFind to another – database changes, URL remappings, etc.

VuFind 1.0RC2 differs substantially from the previous release, 1.0RC1. Many options have been added to the configuration file, and some details of the database structure have changed. To help users of RC1 move on to RC2, a script has been provided to update an existing installation.

Obviously, VuFind installations often feature complex customizations, and an upgrade process cannot be fully automatic. However, these tools should help eliminate some of the more tedious tasks involved.

Before you run the upgrade script, make sure you have done these things:

• Take VuFind offline to prevent new data being created during the upgrade process.
• Move your RC1 directory to a new location, and unpack RC2 into the old RC1 location. DO NOT UNPACK RC2 ON TOP OF RC1. It is very important that you maintain separate directories. Your RC1 directory will not be modified by this process, so you can revert fairly easily if you need to by simply moving directories around.
• Back up your MySQL database. This script will also make backups for you, but you should make your own backup just in case something goes wrong.
• Make sure your PHP installation has access to the PDO MySQL driver. While VuFind itself doesn't currently access MySQL through PDO, the upgrade script does.

Switch to the directory where you installed RC2. In Linux environments, run upgrade/RC1toRC2.sh. In Windows environments, run upgrade\RC1toRC2.bat. The upgrade process will prompt you for further details and remind you about some of the information found on this page.

If you run into problems running the script, you may wish to revert to your backed-up MySQL database and unpack a fresh copy of RC2 before trying again. Running the upgrade script repeatedly on the same directory/database may have undesirable side effects.

Once the upgrade script completes successfully, your database will be RC2-compatible and you will have a file that can be used as your new config.ini after some review. You still have a bit of work left to do, however….

The upgrade script creates a file called web/config/config.ini.rc2 containing suggested config.ini settings. You should review the file's contents. If you are happy with it, rename it to config.ini and overwrite the default file.

Because of limitations of the upgrade script, there are a few things you should pay close attention to when reviewing the merged config.ini.rc2 file:

• Disabled settings from your RC1 configuration may get turned back on. You will have to comment them back out again.
• Comments from your RC1 file will be lost and replaced with the new default comments from the RC2 file – if you have important information embedded there, you will need to merge it by hand.
• Boolean “true” will map to “1” and “false” will map to ””. This is functionally equivalent, but you may want to adjust the file for readability.

The upgrade script does not attempt to update your ILS configuration, which is generally in a separate .ini file in the web/conf folder (i.e. Voyager.ini). You should be able to copy your RC1 ILS configuration file directly to the RC2 installation without changes.

If you have customized your Apache configuration in RC1's httpd-vufind.conf, you may need to merge those customizations into the new RC2 file – this is not automated by the upgrade script. You should also be sure that Apache is linking to the correct configuration file (though if you installed RC2 in a location where RC1 used to exist, this should already be taken care of).

Check the Solr configuration in the solr directory and the SolrMarc configuration in the import directory. These are not touched by the upgrade script and will most likely require some manual adjustments.

RC2's Solr schema is significantly different from RC1's (particularly in the way subjects are handled), and the upgrade script does not attempt to merge your customizations to the Solr schema or SolrMarc MARC mappings with the new installation. You will have to do this by hand.

Note that the version of SolrMarc included with RC2 is a great deal more configurable than the version in RC1. You may be able to achieve your old customizations more easily, without the need to build your own customized version of the SolrMarc .jar file. See the changelog for more details on new features.

Once you are satisfied with your SolrMarc configuration, REINDEX ALL OF YOUR RECORDS. Attempting to run RC2 with an RC1-generated index will not work.

Obviously, if you have customized RC1's code or templates, these changes will have to be reintegrated with your RC2 installation. New features like template inheritance and external configuration files for search types make customization much easier than in the past, so you may be able to achieve the same effects as in the past with fewer low-level code changes. See the changelog for more details, and feel free to ask questions on the vufind-tech mailing list if you need help!

The URL for search results for RC1 was in the format of (base URL)/Search/Home…, but in RC2 (and earlier trunk revisions since 1197), this changes to (base URL)/Search/Results… Because of this change, bookmarks to old search results (and links in outdated templates) will no longer work. If this is a concern for you, one relatively benign fix is to add another set of rewrite rules to your Apache config (e.g. your httpd-vufind.conf file). Here is a basic example which should work in most cases:

RewriteCond %{QUERY_STRING} (^|&)(lookfor|tag)=
RewriteRule ^Search/Home Search/Results [R=301,L]

These should be the first rewrite rules in your config.

Note: I had problems with the above snippet messing up URLs containing URL-encoded characters; eventually I resorted to avoiding the redirect and instead using these lines:

# Compatibility with RC1, which used "Home" instead of "Results":
RewriteCond   %{QUERY_STRING} (^|&)(lookfor|tag|filter\[\])=
RewriteRule   ^Search/Home                  index.php?module=Search&action=Results [B,L,QSA]

If you notice problems with the paging mechanism (links to subsequent pages of search results do not work), make sure that the PEAR Pager module is updated to the latest version (2.4.8 or later). You can enter “pear upgrade Pager” at the command line to update the module. This update should be taken care of by the upgrade script, but if you upgrade piecemeal without using the script, you may encounter this problem.