wiki:faq/drupal/upgrade

Version 19 (modified by Jamie McClelland, 9 years ago) (diff)

--

Upgrading your Drupal installation at May First/People Link

May First/People Link will update your Drupal installation for you, however, we cannot upgrade your Drupal installation. The difference between update and upgrade is:

update
changing minor versions. Updates represent small changes, usually to fix bugs and security holes. In the Drupal 4 branch, examples of minor version changes are: 4.7.4 to 4.7.5. In the Drupal 5 branch, examples of minor version changes are 5.1 to 5.2.
upgrade
an upgrade means changing between major Drupal versions. That means going from 4.6 to 4.7. Or from 4.7 to 5. Or from 5 to 6.

Why doesn't May First/People Link do major upgrades? We would love to! However, it is a complicated process that is different for each site. In other words, we cannot automate the process, like we can for minor updates. If we upgraded everyone's Drupal web site we would have no time to do anything else!

How to upgrade

If you would like to upgrade your site, here are directions for how to do that. If you are not comfortable doing this, and you are able to hire a developer to help, please post a ticket of the type "Project/Need to hire someone" and we will try to match you with a techie.

In addition, these directions are for upgrading from 4.7 to 5, however, they also apply if you are upgrading from 4.6 or from 5 to 6. Please remember - you must upgrade incrementally. In other words, you can't go directly from 4.6 to 6. You must first upgrade from 4.6 to 4.7, and then upgrade from 4.7 to 5 and then from 5 to 6, etc.

  • Assemble your team. To upgrade Drupal, you will need someone who is comfortable using the command line and using secure shell (ssh). If that is not you, you may want to recruit some helpers.
  • Plan the upgrade. You should be prepared to spend several hours upgrading your site. If all goes smoothly you won't need that time, however, it's better to be prepared. Before beginning, review all of the third party modules that you have installed. You can review these modules by looking in your web/sites/default/modules directory. For each module installed, search the http://drupal.org web site to find the Drupal version of the module corresponding to the Drupal version you are upgrading to. If you can't find an appropriate version (this happens often) you will not be able to use it! For each module, download the new version to your local computer.
  • Make a list of custom scripts and other special templates you may have in your theme's directory. If you are using Drupal without any customization ("out of the box") with a standard theme (e.g. Bluemarine), your upgrade will go very smoothly. If you have customized scripts and pages, these may break after the upgrade (requiring you to tweak them). If you do have a heavily customized theme, you may consider switching to a core theme before the upgrade. Then, upgrade your theme (there are notes for doing this on drupal.org), and finally try switching back to your custom theme.
  • Upgrade all your third party modules to the most recent version. If you are rnning Drupal 5 and upgrading to Drupal 6, ensure all third party modules are at the most recent Drupal 5 version first. You can do this easily with drush. From the command line, in your web directory, type:
    drush update
    
  • Test to make sure your site is still functioning properly before you continue.
  • Make a backup! You will want to backup both your directories and your database. To backup these up, ssh into your server and run the following commands (replacing YOURDOMAIN with your actual domain name and YOURDATABASE with the name of your database):
cp -r -p YOURDOMAIN/web web.backup
mysqldump YOURDATABASE  > drupal_db.backup.sql
  • Login to your Drupal site as the user with User ID 1. If that user is mayfirst, then change the mayfirst user's password and log in as the mayfirst user. You must be logged in with user id 1 for the upgrade to work properly. If you are not sure what user id you are logged in as, click the My Account link in your menu and look at the web address you are sent to. It will say: /user/3 if you are user id 3. Or /user/1 if you are user id 1.
  • Go to your admin/settings page and check the box to indicate that your site is down for maintenance.
  • Disable all third party modules. Go to the modules admin section of your web site. Compare the enabled modules with your list of third party modules. You can find a list of your third party modules by looking in your web/sites/default/modules directory. Uncheck each third party module that is checked.
  • Using secure FTP or ssh, rename the modules directory your sites/default/modules directory to modules.d5. Create a new, empty modules directory.
  • Using ssh, change into your web directory. Replace YOURDOMAIN with your actual domain:
    cd YOURDOMAIN/web
    
  • Run the mf-change-drupal-symlinks script. Run the following command
    mf-change-drupal-symlinks
    
  • Follow the directions for updating your database. Copy and paste all the output in case you run into problems later - it will be useful to reference it.
  • Test your site. Remember - your third party modules will not yet be working!
  • One by one, add the drupal 5 version of each third party module to your modules directory (web/sites/default/modules) and enable it via Drupal. After enabling each module, return to the update.php script to run any needed database updates.

When you are done - report your results! Let us know how it goes. Edit this page to add new lessons learned.

Gotchas

Rebuilding Permissions

  • Just learned a lesson about the upgrade process and wanted to share it. When you upgrade, you may find that "normal" users can't access your site's content even though the permissions appear to be correct. The solution is to rebuild the permissions cache, which you can find via Adminster > Content Management > Post Settings. At the top of that page, you'll see an option to rebuild permissions. Hit the button to rebuild permissions and you should find that your site content is now accessible.

CCK and Drupal 6

  • For people already upgrading from Drupal 5 to 6 who have the module Content Construction Kit installed, here's an important reminder:

Before upgrading your site to Drupal 6, you must upgrade CCK to version 5.x-1.9 and run all updates. Updating to 5.x-1.9 is especially important before an upgrade because that version includes a fix to ensure you don't lose data when you disable modules in preparation for the upgrade.

So you upgrade to the latest CCK and then run the update script in Drupal 5, before doing the Drupal upgrade.