This page should be used to suggest best practices for moving from one version of VuFind to another – database changes, URL remappings, etc.
Note: This is pre-release documentation; do not consider it official until after the release of version 1.0 of the software!
VuFind 1.0 features many improvements over the previous release, 1.0RC2. Fortunately, the database structure has not changed, but updates to the Solr index and configuration files require a bit of work in order to upgrade. Some refactoring of the code may also impact your local customizations.
The notes below should help you automate some upgrade tasks and understand what needs to be done manually.
Note that if you are working with a version earlier than 1.0RC2, please upgrade to RC2 BEFORE following any of these instructions (see notes lower on the page).
Before you run the upgrade script, make sure you have done these things:
Switch to the directory where you installed 1.0. In Linux environments, run upgrade/RC2to1-0.sh. In Windows environments, run upgrade\RC2to1-0.bat. The upgrade process will prompt you for further details and remind you about some of the information found on this page.
Once the upgrade script completes successfully, your database will be bug-free 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 several files in the web/conf directory: config.ini.new, facets.ini.new and searches.ini.new. Each of these files contains a suggested configuration based on a blend of new settings introduced by VuFind 1.0 and old settings found in your 1.0RC2 installation. You should review each file's contents, and if you are happy with it, rename it to remove the ”.new” and overwrite the blank default configuration file. (For example, rename config.ini.new to config.ini).
Because of limitations of the upgrade script, there are a few things you should pay close attention to when reviewing the merged ini files:
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 RC2 ILS configuration file directly to the 1.0 installation without changes.
If you have customized your Apache configuration in RC2's httpd-vufind.conf, you may need to merge those customizations into the new 1.0 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 1.0 in a location where RC2 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.
Due to changes in the latest version of SolrMarc, any custom indexing scripts you wrote are now found in the import/index_scripts directory rather than in import/scripts. When you copy your customizations from the old version, be sure you put them in the right place!
1.0's Solr schema has some differences from RC2's (mainly due to the introduction of record drivers), 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.
Once you are satisfied with your SolrMarc configuration, REINDEX ALL OF YOUR RECORDS. Attempting to run 1.0 with an RC2-generated index will not work correctly.
If you have changed search options in web/conf/searchspecs.yaml, you should manually update 1.0's version. It differs in a couple of small but significant ways from RC2's version, and the automatic tools do not merge your customizations for you.
Obviously, if you have customized RC2's code or templates, these changes will have to be reintegrated with your 1.0 installation. The biggest changes have to do with the way records are displayed – a lot of code on the record view and search results screens has been moved into a record driver module. If you have customized record views, you may have to reimplement your changes in a slightly different way. Hopefully the greatly improved flexibility of the new model makes it worth the effort! Feel free to ask questions on the vufind-tech mailing list if you need help!
Remember, if you do a lot of local customizations and find the upgrade process unreasonably tedious, you may be able to make your life easier by using Subversion Vendor Branching.
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:
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:
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.