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

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
installation:migration_notes [2017/07/19 15:57] – [Step-by-Step] demiankatzinstallation:migration_notes [2024/02/07 15:47] (current) demiankatz
Line 1: Line 1:
-====== VuFind Migration Notes ======+====== VuFind® Migration Notes ======
  
-This page provides notes on upgrading to the latest VuFind release from earlier versions.+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:installation:migration_notes|legacy migration notes]] page//+:!Please note that even though most of the version-specific notes here refer to very old versions, the information is still relevant to current releases. The process has simply remained stable for many years.
  
-===== Migrating from VuFind 2.x or Newer to the Latest Release =====+===== Migrating from VuFind® 2.x or Newer to the Latest Release =====
  
-Upgrading from VuFind 2.x or newer is relatively easy, assuming that you isolate all of your changes to the [[configuration:local_settings_directory|local settings directory]], [[development:architecture:customizing_vufind#modules|custom module]] and [[development:architecture:customizing_vufind#themes|local theme]].+Upgrading from VuFind® 2.x or newer is relatively easy, assuming that you isolate all of your changes to the [[configuration:local_settings_directory|local settings directory]], [[development:architecture:customizing_vufind#modules|custom module]] and [[development:architecture:customizing_vufind#themes|local theme]].
  
 :!: Note that if you have made customizations to your Solr schema or configuration, these changes will need to be reapplied manually. :!: Note that if you have made customizations to your Solr schema or configuration, these changes will need to be reapplied manually.
Line 15: Line 15:
 ==== Step-by-Step ==== ==== 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:+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:
  
-  - 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.+  - 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 -- this is particularly important for the solr/vendor directory.     - :!: 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 -- this is particularly important for the solr/vendor directory.
   - If you are installing from Git rather than a downloaded archive, run "composer install" to update dependencies.   - 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 [[configuration:local_settings_directory|local settings directory]] may be written by the web server and that autoConfigure is turned on in the [System] section of [[configuration:files:config.ini]].   - Make sure that the config/vufind subdirectory of your [[configuration:local_settings_directory|local settings directory]] may be written by the web server and that autoConfigure is turned on in the [System] section of [[configuration:files:config.ini]].
   - Empty out the cache subdirectory of your [[configuration:local_settings_directory|local settings directory]] to be sure no incompatible settings are cached.   - Empty out the cache subdirectory of your [[configuration:local_settings_directory|local settings directory]] to be sure no incompatible settings are cached.
-  - Visit <nowiki>http://your-server/vufind/Upgrade/Home</nowiki> 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.+  - Visit <nowiki>http://your-server/vufind/Upgrade/Home</nowiki> 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.   - 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 [[configuration:files:config.ini]] for security.   - Disable web server write access to the config/vufind subdirectory and turn off autoConfigure in [[configuration:files:config.ini]] for security.
Line 28: Line 28:
 :!: 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 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.+:!: 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, [[http://blog.library.villanova.edu/libtech/2015/07/23/automatically-updating-locally-customized-files-with-git/|this blog post]] offers a strategy for automatically updating them with the help of Git. :!: If you have to maintain a significant number of custom templates, [[http://blog.library.villanova.edu/libtech/2015/07/23/automatically-updating-locally-customized-files-with-git/|this blog post]] offers a strategy for automatically updating them with the help of Git.
Line 38: Line 38:
 === Special Notes on Upgrading with PostgreSQL === === 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:+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:
  
 <code>psql -U [your-vufind-username] -d [your-vufind-database-name] -a -f [path/to/migration.sql]</code> <code>psql -U [your-vufind-username] -d [your-vufind-database-name] -a -f [path/to/migration.sql]</code>
Line 44: Line 44:
 === Special Notes on Upgrading from 2.x to 3.x === === Special Notes on Upgrading from 2.x to 3.x ===
  
-VuFind 2.x uses Solr 4 while VuFind 3.x uses Solr 5. If you are upgrading from 2.x to 3.x, you will notice some important changes: the solr directory contents will be structured differently, and the VuFind start/stop script will be called "solr.sh/solr.bat" instead of "vufind.sh/vufind.bat".+VuFind® 2.x uses Solr 4 while VuFind® 3.x uses Solr 5. If you are upgrading from 2.x to 3.x, you will notice some important changes: the solr directory contents will be structured differently, and the VuFind® start/stop script will be called "solr.sh/solr.bat" instead of "vufind.sh/vufind.bat".
  
 Before unpacking the 3.x distribution on top of 2.x, it is recommended that you follow these steps: Before unpacking the 3.x distribution on top of 2.x, it is recommended that you follow these steps:
  
 - Delete vufind.sh/vufind.bat to prevent confusion. If you wish to retain these script names for your existing workflows, create simple wrapper scripts around solr.sh/solr.bat - Delete vufind.sh/vufind.bat to prevent confusion. If you wish to retain these script names for your existing workflows, create simple wrapper scripts around solr.sh/solr.bat
-- Rename your existing solr directory to solr_old (this way you can easily revert if you have problems with the upgrade; after successfully reindexing your data and testing your upgraded VuFind, you can remove the solr_old directory). +- Rename your existing solr directory to solr_old (this way you can easily revert if you have problems with the upgrade; after successfully reindexing your data and testing your upgraded VuFind®, you can remove the solr_old directory). 
-===== Migrating from VuFind 1.x =====+===== Migrating from VuFind® 1.x =====
  
-:!: You should not upgrade directly from VuFind 1.x to VuFind 3.0 or newer. If you still have a 1.x instance, it is recommended that you upgrade from VuFind 1.x to the latest VuFind 2.x release, and then from there to the newest version.+:!: You should not upgrade directly from VuFind® 1.x to VuFind® 3.0 or newer. If you still have a 1.x instance, it is recommended that you upgrade from VuFind® 1.x to the latest VuFind® 2.x release, and then from there to the newest version.
  
-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.+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.+  * Make sure that VuFind® 1 is running -- the upgrade script will need access to your Solr index.
   * Upgrade Java to 1.7 if needed.   * Upgrade Java to 1.7 if needed.
-  * Install a copy of VuFind 2 according to the [[:installation|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). +  * Install a copy of VuFind® 2 according to the [[:installation|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 <nowiki>http://your-server/vufind/Install/Home</nowiki> to configure VuFind, use <nowiki>http://your-server/vufind/Upgrade/Home</nowiki> and follow the on-screen prompts.+  * Instead of navigating to <nowiki>http://your-server/vufind/Install/Home</nowiki> to configure VuFind®, use <nowiki>http://your-server/vufind/Upgrade/Home</nowiki> and follow the on-screen prompts.
   * The automatic upgrade will handle most of your configurations, but several things will require manual attention:   * 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 [[development:architecture:customizing_vufind#modules|custom module]].     * Custom code - most code changes can now be isolated to a [[development:architecture:customizing_vufind#modules|custom module]].
     * Custom themes - 2.0 themes use PHP templates instead of Smarty and have a different directory structure -- see [[development:architecture:user_interface|customizing the user interface]]. Note that the [[https://github.com/TriCollegeLibraries/smarty2php|smarty2php]] tool may help automate some of the template upgrading, though it will still require significant manual effort.     * Custom themes - 2.0 themes use PHP templates instead of Smarty and have a different directory structure -- see [[development:architecture:user_interface|customizing the user interface]]. Note that the [[https://github.com/TriCollegeLibraries/smarty2php|smarty2php]] tool may help automate some of the template upgrading, though it will still require significant manual effort.
     * Solr schema/configuration changes     * Solr schema/configuration changes
-  * Shut down VuFind 1, reindex your records into VuFind 2, and start VuFind 2's Solr instance.+  * 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 [[configuration:local_settings_directory|local settings directory]] and turn off autoConfigure in the [System] section of [[configuration:files:config.ini]].   * For security, disable web server write access to the config/vufind subdirectory of your [[configuration:local_settings_directory|local settings directory]] and turn off autoConfigure in the [System] section of [[configuration:files:config.ini]].
  
-Obviously, it is strongly recommended that you prepare your VuFind 2.x upgrade on a test server prior to doing this in production -- porting old customizations is not a trivial process.+Obviously, it is strongly recommended that you prepare your VuFind® 2.x 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 [[http://vufind.org/support.php|support page]] if you have questions or problems. Remember that help is available at the [[http://vufind.org/support.php|support page]] if you have questions or problems.
 ---- struct data ---- ---- struct data ----
 +properties.Page Owner : 
 ---- ----
  
installation/migration_notes.1500479864.txt.gz · Last modified: 2017/07/19 15:57 by demiankatz