// $Id: UPGRADE.txt,v 1.12 2008/01/04 16:15:58 goba Exp $ UPGRADING DRUPAL 6.x --------- It is recommended that you run through the entire upgrade process on a test site. Once you are confident that the upgrade has been successful, you can then either replicate the steps on your live site or migrate the database and files from the test site to the live site. Migration from test site to live site is outside the scope of this document. This document assumes that you are familiar with the concepts of core, custom and contributed modules and that you understand where they are placed in your Drupal installation. To prepare for an upgrade: 1. Check that your system meets or exceeds the minimum requirements for the upgrade. For more information, see http://drupal.org/requirements. 2. If this is a major upgrade (5.x to 6.x), locate and download compatible versions of your contributed modules and themes. A major upgrade will also require new versions of custom modules and themes. - For Drupal 6 versions of contributed modules, see http://drupal.org/project/modules - For information about how to convert a Drupal 5 custom module to Drupal 6, see http://drupal.org/update/modules - For Drupal 6 versions of contributed themes, see http://drupal.org/project/themes - For information on converting a Drupal 5 custom theme to Drupal 6, see http://drupal.org/update/theme. 3. Read through this entire document and read any upgrade.txt files found in the new versions of contributed modules. If you use the CCK module, be sure to read the upgrade.txt file supplied with the Drupal 6 version. 4. Make a backup of your entire site, database and files. 5. If you are performing a major upgrade (5.x to 6.x), update the existing site to the most recent 5.x version of Drupal and update all your contributed modules to the latest 5.x versions. See the upgrade.txt file in your Drupal 5 installation for more information. 6. If the existing site has installed modules that you are no longer using, this would be a good point to uninstall them. Check if there is an uninstall routine available on the Uninstall tab of the Modules admin page. To perform an upgrade: 1. Make a full backup of the database, sites directory, files directory and customized files such as .htaccess and robots.txt. 2. If possible, log on with user ID 1, which is the first account created and the main administrator account. User ID 1 will be able to automatically access update.php in step #10. There are special instructions in step #10 if you are unable to log on as user ID 1. Do not close your browser until the final step is complete. 3. Place the site in "Off-line" mode, to let the database updates run without interruption and to avoid displaying errors to end users of the site. This option is at http://www.example.com/?q=admin/settings/site-maintenance (replace www.example.com with your installation's domain name and path). 4. If you are using a custom or contributed theme, switch to a core theme, such as Garland or Bluemarine. 5. Disable all custom and contributed modules. 6. Make another backup of the database. This backup is not strictly necessary, but if you run into a problem and want to redo some of the following steps, you can save some time by restoring this backup. 7. Remove all the files and directories from the Drupal installation directory. 8. Unpack the new files and directories into the Drupal installation directory. **The remaing steps are different for minor (for example 6.1 to 6.2) and major (5.x to 6.x) upgrades. If you are performing a major upgrade, skip down to the MAJOR UPGRADE section** MINOR UPGRADE ONLY: 9. Copy the backed up files and sites directories to your Drupal installation. If other system files such as .htaccess or robots.txt were customized, copy the backed up versions to your Drupal installation. 10. Run update.php by visiting http://www.example.com/update.php (replace www.example.com with your Drupal installation's domain name and path). This step will update the core database tables to the new Drupal installation. Note: if you are unable to access update.php do the following: - Open your settings.php file with a text editor. - Find the line that says $update_free_access = FALSE; and change it to $update_free_access = TRUE; Once update.php has been run, you must change this line back to $update_free_access = FALSE; 11. Return your site to "Online" mode so that your visitors may resume browsing. As in step #3, this option is available in your administration screens at http://www.example.com/?q=admin/settings/site-maintenance (replace www.example.com with your installation's domain name and path). MAJOR UPGRADE ONLY: 9. Copy your backed up files directory to the Drupal installation directory. If other system files such as .htaccess or robots.txt were customized, open the new versions of the files and re-create the modifications. 10. In the sites/default directory make a copy of the default.settings.php file and rename the copy as "settings.php". Do not delete or change the default.settings.php file. 11. Using your Drupal 5 settings.php file as a guide, update the database connection settings in the new settings.php file. Note: For a multisite configuration, there may be several settings.php files located in a structure like the following: sites/default/settings.php sites/example.com/settings.php sites/sub.example.com/settings.php sites/sub.example.com.path/settings.php More information on multisite configuration is located in INSTALL.txt. 12. For each custom and contributed module, do the following: - Copy the module to its previous location (usually sites/all/modules) - Enable the module - Run update.php - Repeat until all contributed and custom modules have been updated. Note that some sets of modules (for example, CCK) may require you to enable and update the modules in a particular order. See the module documentation for more information. 13. Copy the Drupal 6 version of your theme to the Drupal installation and enable it. 14. Return your site to "Online" mode so that your visitors may resume browsing. This option is available in your administration screens at http://www.example.com/?q=admin/settings/site-maintenance (replace www.example.com with your installation's domain name and path). For more information on upgrading, visit the Drupal handbook at http://drupal.org/upgrade