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.
legacy:installation:migration_notes

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
legacy:installation:migration_notes [2015/12/08 19:54] – ↷ Links adapted because of a move operation demiankatzlegacy:installation:migration_notes [2018/12/19 17:03] (current) demiankatz
Line 1: Line 1:
 ====== Migration Notes ====== ====== Migration Notes ======
  
-This page should be used to suggest best practices for moving from one version of VuFind to another -- database changes, URL remappings, etc. +// This outdated page has been deleted to prevent confusion; for current documentation, see [[installation:migration_notes|this page]]. To view old content for historical interest, see the "Old Revisions" list below. //
- +
-Next to upgrading via upgrade script, there's also the possibility to use a versioning control-tool (for example [[:subversion#upgrading_an_old_custom_vufind_version_using_subversion|Subversion]]) +
- +
-===== Upgrading to 2.x ===== +
- +
-See the [[vufind2:migration_notes|VuFind 2.x migration notes]] page. +
- +
-===== Upgrading 1.3 to 1.4 ===== +
- +
-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.3, please upgrade to 1.3 BEFORE following any of these instructions (see notes lower on the page). +
- +
-==== Preparations ==== +
- +
-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 1.3 directory to a new location, and unpack 1.4 into the old 1.3 location.  DO NOT UNPACK 1.4 ON TOP OF 1.3.  It is very important that you maintain separate directories.  Your 1.3 directory will not be modified by this process, so you can revert fairly easily if you need to by simply moving directories around. +
-  * If you are using a platform that requires special permission settings to allow write access to critical VuFind directories, don't forget to apply these to the new install (for example, see notes for [[legacy:installation:fedora#download_vufind|Fedora]] or [[legacy:installation:ubuntu#download_vufind|Ubuntu]]). +
-  * Back up your MySQL database.  The upgrade script makes only trivial changes to the database, but you should make a 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.  The automatic upgrade process does not currently support databases other than MySQL. +
- +
-==== Running the Script ==== +
- +
-Switch to the directory where you installed 1.4.  In Linux environments, run upgrade/1-3to1-4.sh.  In Windows environments, run upgrade\1-3to1-4.bat.  The upgrade process will prompt you for further details and remind you about some of the information found on this page. +
- +
-==== Next Steps ==== +
- +
-Once the upgrade script completes successfully, your database will be updated 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.... +
- +
-=== ini File Cleanup === +
- +
-The upgrade script creates several files in the web/conf directory: config.ini.new, facets.ini.new, searches.ini.new, etc.  Each of these files contains a suggested configuration based on a blend of new settings introduced by VuFind 1.4 and old settings found in your 1.3 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: +
- +
-  * Disabled settings from your 1.3 configuration may get turned back on.  You will have to comment them back out again. +
-  * Comments from your 1.3 files will be lost and replaced with the new default comments from the 1.4 files -- 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. +
- +
-== Database INI File == +
- +
-If you are not using the default database name of "vufind", the upgrade process will automatically copy web/conf/vufind.ini to web/conf/[your_database_name].ini.  No manual action should be necessary. +
- +
-== OAI-PMH Harvest Settings == +
- +
-If you are using the OAI-PMH harvester, you can copy your old harvest/oai.ini file into the new installation and it should continue to work. +
- +
-=== ILS Configuration === +
- +
-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 1.3 ILS configuration file directly to the 1.4 installation without changes. +
- +
-=== Apache Configuration === +
- +
-If you have customized your Apache configuration in 1.3's httpd-vufind.conf, you may need to merge those customizations into the new 1.4 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.4 in a location where 1.3 used to exist, this should already be taken care of). +
- +
-=== Solr / SolrMarc Configuration === +
- +
-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. +
- +
-1.4's Solr schema adds several new fields to support [[:hierarchies_and_collections]].  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, it is recommended that you [[:re-indexing|reindex all of your records]].  While the 1.4 schema should be compatible with the 1.3 schema, and both releases use the same Solr version, upgrades are a good time to refresh your index. +
- +
-=== Other Configuration Files === +
- +
-If you have changed search options in web/conf/searchspecs.yaml (or any of the other YAML configuration files), you should manually update 1.4's version.  Several syntax issues have been corrected since 1.3, and you should make sure your configurations contain fully valid YAML.  Old 1.3 configurations will continue to work in 1.4, but fixing syntax issues now will make future upgrades to 2.x easier. +
- +
-=== Code and Template Customization === +
- +
-Obviously, if you have customized 1.3's code or templates, these changes will have to be reintegrated with your 1.4 installation.  Most of 1.4's template changes have to do with its new [[:hierarchies_and_collections]] functionality.  Feel free to ask questions on the [[https://lists.sourceforge.net/mailman/listinfo/vufind-tech|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|Subversion Vendor Branching]]. +
- +
-===== Upgrading 1.2 to 1.3 ===== +
- +
-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.2, please upgrade to 1.2 BEFORE following any of these instructions (see notes lower on the page). +
- +
-==== Preparations ==== +
- +
-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 1.2 directory to a new location, and unpack 1.3 into the old 1.2 location.  DO NOT UNPACK 1.3 ON TOP OF 1.2.  It is very important that you maintain separate directories.  Your 1.2 directory will not be modified by this process, so you can revert fairly easily if you need to by simply moving directories around. +
-  * If you are using a platform that requires special permission settings to allow write access to critical VuFind directories, don't forget to apply these to the new install (for example, see notes for [[legacy:installation:fedora#download_vufind|Fedora]] or [[legacy:installation:ubuntu#download_vufind|Ubuntu]]). +
-  * Back up your MySQL database.  The upgrade script makes only trivial changes to the database, but you should make a 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.  The automatic upgrade process does not currently support databases other than MySQL. +
- +
-==== Running the Script ==== +
- +
-Switch to the directory where you installed 1.3.  In Linux environments, run upgrade/1-2to1-3.sh.  In Windows environments, run upgrade\1-2to1-3.bat.  The upgrade process will prompt you for further details and remind you about some of the information found on this page. +
- +
-==== Next Steps ==== +
- +
-Once the upgrade script completes successfully, your database will be updated 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.... +
- +
-=== ini File Cleanup === +
- +
-The upgrade script creates several files in the web/conf directory: config.ini.new, facets.ini.new, searches.ini.new, etc.  Each of these files contains a suggested configuration based on a blend of new settings introduced by VuFind 1.3 and old settings found in your 1.2 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: +
- +
-  * Disabled settings from your 1.2 configuration may get turned back on.  You will have to comment them back out again. +
-  * Comments from your 1.2 files will be lost and replaced with the new default comments from the 1.3 files -- 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. +
- +
-== Database INI File == +
- +
-If you are not using the default database name of "vufind", the upgrade process will automatically copy web/conf/vufind.ini to web/conf/[your_database_name].ini.  No manual action should be necessary. +
- +
-== OAI-PMH Harvest Settings == +
- +
-If you are using the OAI-PMH harvester, you can copy your old harvest/oai.ini file into the new installation and it should continue to work. +
- +
-=== ILS Configuration === +
- +
-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 1.2 ILS configuration file directly to the 1.3 installation without changes. +
- +
-=== Apache Configuration === +
- +
-If you have customized your Apache configuration in 1.2's httpd-vufind.conf, you may need to merge those customizations into the new 1.3 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.3 in a location where 1.2 used to exist, this should already be taken care of). +
- +
-=== Solr / SolrMarc Configuration === +
- +
-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. +
- +
-1.3's Solr schema has one significant difference from 1.2's (the addition of a publishDateSort field necessitated by changes in Solr 3.x).  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, [[:re-indexing|REINDEX ALL OF YOUR RECORDS]].  Attempting to run 1.3 with a 1.2-generated index may not work correctly since the new release uses a much newer version of Solr. +
- +
-=== Other Configuration Files === +
- +
-If you have changed search options in web/conf/searchspecs.yaml, you should manually update 1.3's version.  It has a couple of additions since 1.2's version, and the automatic tools do not merge your customizations for you. +
- +
-=== Code and Template Customization === +
- +
-Obviously, if you have customized 1.2's code or templates, these changes will have to be reintegrated with your 1.3 installation.  Most of 1.3's template changes have to do with its new bulk "book bag" functionality.  Feel free to ask questions on the [[https://lists.sourceforge.net/mailman/listinfo/vufind-tech|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|Subversion Vendor Branching]]. +
- +
-===== Upgrading 1.1 to 1.2 ===== +
- +
-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.1, please upgrade to 1.1 BEFORE following any of these instructions (see notes lower on the page). +
- +
-==== Preparations ==== +
- +
-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 1.1 directory to a new location, and unpack 1.2 into the old 1.1 location.  DO NOT UNPACK 1.2 ON TOP OF 1.1.  It is very important that you maintain separate directories.  Your 1.1 directory will not be modified by this process, so you can revert fairly easily if you need to by simply moving directories around. +
-  * If you are using a platform that requires special permission settings to allow write access to critical VuFind directories, don't forget to apply these to the new install (for example, see notes for [[legacy:installation:fedora#download_vufind|Fedora]] or [[legacy:installation:ubuntu#download_vufind|Ubuntu]]). +
-  * Back up your MySQL database.  The upgrade script makes only trivial changes to the database (adding a new column), but you should make a 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.  The automatic upgrade process does not currently support databases other than MySQL. +
- +
-==== Running the Script ==== +
- +
-Switch to the directory where you installed 1.2.  In Linux environments, run upgrade/1-1to1-2.sh.  In Windows environments, run upgrade\1-1to1-2.bat.  The upgrade process will prompt you for further details and remind you about some of the information found on this page+
- +
-==== Next Steps ==== +
- +
-Once the upgrade script completes successfully, your database will be updated 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.... +
- +
-=== ini File Cleanup === +
- +
-The upgrade script creates several files in the web/conf directory: config.ini.new, facets.ini.new, searches.ini.new, etc.  Each of these files contains a suggested configuration based on a blend of new settings introduced by VuFind 1.2 and old settings found in your 1.1 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: +
- +
-  * Disabled settings from your 1.1 configuration may get turned back on.  You will have to comment them back out again. +
-  * Comments from your 1.1 files will be lost and replaced with the new default comments from the 1.2 files -- 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. +
- +
-== Database INI File == +
- +
-If you are not using the default database name of "vufind", you will have to rename web/conf/vufind.ini to web/conf/[your_database_name].ini. +
- +
-== OAI-PMH Harvest Settings == +
- +
-If you are using the OAI-PMH harvester, you can copy your old harvest/oai.ini file into the new installation and it should continue to work. +
- +
-=== ILS Configuration === +
- +
-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 1.1 ILS configuration file directly to the 1.2 installation without changes.  If you are interested in taking advantage of the new holds/renewal functionality introduced for Voyager and Horizon, note that you will have to configure a new driver (VoyagerRestful for Voyager, HorizonXMLAPI for Horizon).  This entails editing the driver setting in config.ini and editing the corresponding driver .ini file. +
- +
-=== Apache Configuration === +
- +
-If you have customized your Apache configuration in 1.1's httpd-vufind.conf, you may need to merge those customizations into the new 1.2 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.2 in a location where 1.1 used to exist, this should already be taken care of). +
- +
-=== Solr / SolrMarc Configuration === +
- +
-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. +
- +
-1.2's Solr schema has one minor difference from 1.1's (the addition of the dewey-raw field to aid with call number browsing).  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, [[:re-indexing|REINDEX ALL OF YOUR RECORDS]].  Attempting to run 1.2 with a 1.1-generated index may not work correctly. +
- +
-=== Other Configuration Files === +
- +
-If you have changed search options in web/conf/searchspecs.yaml, you should manually update 1.2's version.  It has a couple of additions since 1.1's version, and the automatic tools do not merge your customizations for you. +
- +
-=== Code and Template Customization === +
- +
-Obviously, if you have customized 1.1's code or templates, these changes will have to be reintegrated with your 1.2 installation.  Most of the 1.2's template changes have to do with its expanded ILS behavior.  If you have implemented holds in your own way, you may want to reimplement them using VuFind's new standard mechanism ([[http://blog.library.villanova.edu/libtech/2011/06/02/expanded-ils-functionality-in-vufind/|this article]] may help).  Feel free to ask questions on the [[https://lists.sourceforge.net/mailman/listinfo/vufind-tech|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|Subversion Vendor Branching]]. +
- +
-===== Upgrading 1.0.x to 1.1 ===== +
- +
-VuFind 1.1 is another significant upgrade to the software, with many new features and some underlying structural changes.  Whether you are using 1.0 or 1.0.1, the procedure for updating to 1.1 is the same. +
- +
-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.0, please upgrade to 1.0 BEFORE following any of these instructions (see notes lower on the page). +
- +
- +
- +
-==== Preparations ==== +
- +
-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 1.0.x directory to a new location, and unpack 1.1 into the old 1.0.x location.  DO NOT UNPACK 1.1 ON TOP OF 1.0.x.  It is very important that you maintain separate directories.  Your 1.0.x directory will not be modified by this process, so you can revert fairly easily if you need to by simply moving directories around. +
-  * If you are using a platform that requires special permission settings to allow write access to critical VuFind directories, don't forget to apply these to the new install (for example, see notes for [[legacy:installation:fedora#download_vufind|Fedora]] or [[legacy:installation:ubuntu#download_vufind|Ubuntu]]). +
-  * Back up your MySQL database.  The upgrade script makes only trivial changes to the database (to add brand new tables and to correct minor errors caused by an old bug (see [[http://vufind.org/jira/browse/VUFIND-217|VUFIND-217]]), but you should make a 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. +
- +
-==== Running the Script ==== +
- +
-Switch to the directory where you installed 1.1.  In Linux environments, run upgrade/1-0to1-1.sh.  In Windows environments, run upgrade\1-0to1-1.bat.  The upgrade process will prompt you for further details and remind you about some of the information found on this page. +
- +
- +
- +
- +
- +
- +
- +
-==== Next Steps ==== +
- +
-Once the upgrade script completes successfully, your database will be updated and 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.... +
- +
-=== ini File Cleanup === +
- +
-The upgrade script creates several files in the web/conf directory: config.ini.new, facets.ini.new, searches.ini.new, etc.  Each of these files contains a suggested configuration based on a blend of new settings introduced by VuFind 1.1 and old settings found in your 1.0.x installation.  You should review each file's contents, and if you are happy with it, rename it to remove the ".newand 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: +
- +
-  * Disabled settings from your 1.0.x configuration may get turned back on.  You will have to comment them back out again. +
-  * Comments from your 1.0.x files will be lost and replaced with the new default comments from the 1.1 files -- 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. +
- +
-== Database INI File == +
- +
-If you are not using the default database name of "vufind", you will have to rename web/conf/vufind.ini to web/conf/[your_database_name].ini. +
- +
-== OAI-PMH Harvest Settings == +
- +
-If you are using the OAI-PMH harvester introduced in VuFind 1.0.1, you can copy your old harvest/oai.ini file into the new installation and it should continue to work.  However, many new settings have been added, and the idPrefix setting has been deprecated, so it is strongly recommended that you look at the expanded comments in the new version of the file before you overwrite it. +
- +
-=== ILS Configuration === +
- +
-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 1.0.x ILS configuration file directly to the 1.1 installation without changes. +
- +
-=== Apache Configuration === +
- +
-If you have customized your Apache configuration in 1.0.x's httpd-vufind.conf, you may need to merge those customizations into the new 1.1 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.1 in a location where 1.0.x used to exist, this should already be taken care of). +
- +
-=== Solr / SolrMarc Configuration === +
- +
-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. +
- +
-1.1's Solr schema has some differences from 1.0.x's (to support new features like [[:tracking_record_changes]], to eliminate some unused legacy fields, and to resolve issues like [[http://vufind.org/jira/browse/VUFIND-259|VUFIND-259]] and [[http://vufind.org/jira/browse/VUFIND-322|VUFIND-322]]).  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, [[:re-indexing|REINDEX ALL OF YOUR RECORDS]].  Attempting to run 1.1 with a 1.0.x-generated index will not work correctly. +
- +
-=== Other Configuration Files === +
- +
-If you have changed search options in web/conf/searchspecs.yaml, you should manually update 1.1's version.  It differs in a couple of small but significant ways from 1.0.x's version, and the automatic tools do not merge your customizations for you. +
- +
-=== Code and Template Customization === +
- +
-Obviously, if you have customized 1.0.x's code or templates, these changes will have to be reintegrated with your 1.1 installation. +
- +
-Here are a few changes that are likely to affect you: +
- +
-  * VuFind's Javascript files have been moved around so that more JS code is contained inside the theme directories.  This allows the introduction of a new {js} Smarty tag that includes Javascript files in [[:customization#theme_inheritance|theme inheritance]], which makes local customization easier than it used to be.  However, it means that if you have hard-coded Javascript paths in your custom templates, you should replace them with appropriate {js} calls, and if you have customized any of the ajax.js files previously found under the web/services directory, you will need to move your customizations to the renamed files in the web/interface/themes/[your_theme]/js directory. +
-  * All AJAX calls have been changed to use JSON instead of XML, and the AJAX handlers in the various web/services subdirectories have been consolidated into fewer files in the web/services/AJAX directory.  If you have customized any AJAX-related code, you will need to do some work to reconcile it with the new layout...  but take comfort in the fact that the new method makes everything significantly less complicated! +
-  * The [[:other_than_marc|record driver]] interface has been slightly changed to move real-time holdings lookup inside the record drivers, rather than having it hard-coded in the Record/Holdings controller.  This makes it easier for you to control which records VuFind looks up in your ILS.  If you are using custom record drivers, you may need to make some minor adjustments to account for changes to getHoldings(), but for most common applications this will not make a difference to you.  You may also need to implement the new getXML method introduced for [[:tracking_record_changes#oai-pmh_server_functionality|OAI-PMH server support]]. +
-  * Thumbnail URL generation (using bookcover.php) is now largely controlled by the getThumbnail method of the record driver -- this allows easier customization/overriding without huge amounts of template editing, but you may have to update custom templates if they are doing inline generation of bookcover.php links. +
- +
-Feel free to ask questions on the [[https://lists.sourceforge.net/mailman/listinfo/vufind-tech|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|Subversion Vendor Branching]]. +
- +
-=== Dependencies === +
- +
-  * For better support of accented characters, it is recommended that you install PHP's mbstring module.  For details on how to do this, see the PHP section of the [[legacy:installation]] page for your platform. +
-  * The recommended version of [[http://smarty.net|Smarty]] for use with VuFind 1.1 is Smarty 2.6.26.  Most earlier versions should continue to work, but in order to be consistent with current development, it is probably a good idea to upgrade.  This just involves replacing the code in the appropriate directory on your PHP search path (/usr/share/php/Smarty on many Linux systems, or c:\Program Files\PHP\Pear\Smarty under Windows). +
- +
-=== Automation === +
- +
-If you want to take advantage of the new [[:alphabetical_heading_browse]], be aware that you will need to add heading generation to your automated update process in order to keep the browse lists in sync with your index. +
- +
-===== Upgrading to 1.0.1 ===== +
- +
-VuFind 1.0.1 is a minor maintenance release.  If you are upgrading from RC2, you can follow the instructions for upgrading to 1.0 below.  If you are upgrading from 1.0, there are no significant structural changes to worry about.  In Ubuntu, you can install the new DEB package to upgrade automatically.  In other platforms, make a backup of your 1.0 installation, load 1.0.1 in its place, and then restore whatever portions you have customized -- generally the web/conf and solr directories plus any local templates. +
- +
-===== Upgrading RC2 to 1.0 ===== +
- +
-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). +
- +
-==== Preparations ==== +
- +
-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 RC2 directory to a new location, and unpack 1.0 into the old RC2 location.  DO NOT UNPACK 1.0 ON TOP OF RC2.  It is very important that you maintain separate directories.  Your RC2 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.  The upgrade script makes only trivial changes to the database (to correct errors caused by [[http://vufind.org/jira/browse/VUFIND-186|VUFIND-186]]), but you should make a 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. +
- +
-==== Running the Script ==== +
- +
-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. +
- +
- +
- +
- +
-==== Next Steps ==== +
- +
-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.... +
- +
-=== ini File Cleanup === +
- +
-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: +
- +
-  * Disabled settings from your RC2 configuration may get turned back on.  You will have to comment them back out again. +
-  * Comments from your RC2 file will be lost and replaced with the new default comments from the 1.0 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. +
- +
-=== ILS Configuration === +
- +
-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. +
- +
-=== Apache Configuration === +
- +
-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). +
- +
-=== Solr / SolrMarc Configuration === +
- +
-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 [[:other_than_marc|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, [[:re-indexing|REINDEX ALL OF YOUR RECORDS]].  Attempting to run 1.0 with an RC2-generated index will not work correctly. +
- +
-=== Other Configuration Files === +
- +
-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. +
- +
-=== Code and Template Customization === +
- +
-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 [[:other_than_marc|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 [[https://lists.sourceforge.net/mailman/listinfo/vufind-tech|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|Subversion Vendor Branching]]. +
- +
-===== Upgrading RC1 to RC2 ===== +
- +
-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. +
- +
- +
-==== Preparations ==== +
- +
-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. +
- +
-==== Running the Script ==== +
- +
-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. +
- +
-==== Dealing with Problems ==== +
- +
-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. +
- +
- +
- +
- +
- +
-==== Next Steps ==== +
- +
-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.... +
- +
-=== config.ini Cleanup === +
- +
-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. +
- +
-=== ILS Configuration === +
- +
-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. +
- +
-=== Apache Configuration === +
- +
-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). +
- +
-=== Solr / SolrMarc Configuration === +
- +
-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, [[:re-indexing|REINDEX ALL OF YOUR RECORDS]].  Attempting to run RC2 with an RC1-generated index will not work. +
- +
-=== Code and Template Customization === +
- +
-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 [[https://lists.sourceforge.net/mailman/listinfo/vufind-tech|vufind-tech]] mailing list if you need help! +
- +
-=== Search Result URL Change === +
- +
-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: +
-<code>RewriteCond %{QUERY_STRING} (^|&)(lookfor|tag)= +
-RewriteRule ^Search/Home Search/Results [R=301,L]</code> +
-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: // +
-<code> +
-# 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] +
-</code> +
- +
-==== Common Problems ==== +
- +
-=== Paging Doesn't Work! === +
- +
-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.+
 ---- struct data ---- ---- struct data ----
 +properties.Page Owner : 
 ---- ----
  
legacy/installation/migration_notes.1449604497.txt.gz · Last modified: 2015/12/08 19:54 by demiankatz