Martian Thoughts on Design

We’re continuing on with the tutorials for the Drupal Multi-Site configuration that I set up on my Mac. All the domain and directory structure is based on that tutorial, so if you’ve done something slightly different, you’ll need to adjust as appropriate.

Were following the basic procedure laid out in the UPGRADE.txt in your Drupal core installation, so if you run into any problems you can get some additional tips there.

I’m writing a special tutorial on this because, when we set up our installation in the Building A Drupal Development Environment page, I set up some permissions on the sites/ directory. These permissions made it easier for us to access the files, but we’ll need to tweak a few things in the upgrade procedure to preserve these permissions.

So, in this tutorial, I’m going to show you step by step how to easily accomplish the upgrade.

Step 1: Log into your Drupal site as the administrative user

Hopefully this is pretty self explanatory.

Step 2: Set the site into maintenance mode

Now, you’ll navigate to the Site maintenance page for the site, using the navigation links: Administer > Site configuration > Site maintenance

Step 3: Switch to one of the default themes

If you’ve installed a custom theme, you’ll need to switch out to one of the ones that came with Drupal. I’ll use Garland.

You get there by navigating to: Administer > Site building > Themes.

Make sure that Garland is Enabled, and that it is selected as the Default. Save the configuration.

Step 4: Disable any added modules

We need to disable any modules that we’ve installed, which were not part of the Drupal Core. Navigate to the modules page: Administer > Site building > Modules

You do NOT need to disable anything in Core – required or Core – optional, but disable anything you see in the other section. You can do this by unchecking the box in front of the module. As you go through this, you’ll want to make a list of which modules you’re disabling, so you can turn these back on when we’re done.

When you’ve unchecked the modules, select Save configuration at the bottom of the list when done.

You may need to go through this several times to make sure all the modules are turned off, because some modules are required by others, and can’t be unchecked the first time through.

Step 5: Repeat Steps 1-4

You’ll need to perform Steps 1-4 for each site that you’ve installed. You should be able to see all the sites you have by looking in your ~/Sites/drupal/6/sites/ folder.

Once you’ve gotten all your sites ready for upgrade, return here.

Step 6: Backup the databases

Now we need to make a backup of our databases. We’ll start by opening the Terminal, and navigating to the our ~/Sites/drupal/ folder. Once there, we’ll double check the name of our database.

$ cd ~/Sites/drupal/
$ mysql -u yourrootaccount -p -e "SHOW SCHEMAS"

Again, we’re using yourrootaccount, because I change the name of the root user on my databases as a simple security precaution.

Identify the database for the website, and we’ll back it up. Following my previous examples, I’d need to backup “drupal_sandbox” and “drupal_essentials”, plus the other databases I’ve added. To do this, do the following:

$ /usr/local/mysql/bin/mysqldump -u yourrootuser -p --databases drupal_sandbox drupal_essentials > drupal_20100301.sql

Verify that the file looks correct:

$ ls
$ head -n 100 drupal_20100301.sql

Step 7: Download the latest version of Drupal

You can get this from the Drupal Project Download page. At the time of this writing, Drupal 6.15 is the latest production build, so that’s what we’re using.

Download the file and move it into your ~Sites/drupal/ directory. If your browser is set up to use your user’s Downloads/ folder, switch back to the Terminal and perform the following:

$ cd ~/Downloads/
$ mv drupal-6.15.tar.gz ~/Sites/drupal/

Verify that the file is in your ~/Sites/drupal/ folder.

$ cd ~/Sites/drupal/
$ ls -l

Step 8: Rename the core directory

We’re going to move our Drupal files directory to a new location as a backup. We’re going to need our sites/ folder later on.

$ cd ~/Sites/drupal/
$ sudo mv 6 6_backup

Step 9: Install the new version of Drupal

Now we’ll unpack the new version of Drupal that we downloaded in Step 7. We’re also going to rename it to 6/, as we had in our original installation.

$ tar -xzf drupal-6.15.tar.gz
$ sudo mv drupal-6.15 6

Step 10: Copy the old files back to the new installation

Now we need to move all of our custom files back into the new directory.

To start with, we need to make sure we grab the cronall script we created in Building a Drupal development environment on Mac OS X.

$ cp 6_backup/cronall.php 6/

If you’ve modified any other files, in Drupal’s core (e.g. .htaccess, robots.txt, or something in themes/), copy those into the 6/ folder now.

Now we’re at the step where we need to make sure to preserve the permissions for the webserver. In order to do this we’ll use the cp -Rp command. You’ll need to make sure to include the sudo command in front of the copy command, or you’ll loose the permissions in the sites/ folder. So run the following in the Terminal:

$ sudo cp -Rp 6_backup/sites 6/

Verify that the folders in sites still have the www group.

$ ls -l 6/sites/

Step 11: Run the update

Go back to your browser and run the update script:

http://drupal6.local/update.php

Follow the screen prompts, using the defaults. You should select Continue and then Update, and the process will run automatically. Select the Administration pages link at the end of the process.

Step 12: Check the Status Report

You’ll want to verify that the update process ran correctly by checking the status report. Navigate to Administer > Reports > Status report and click run cron manually.

You should see the new version at the top of the table, and everything else should be green.

Step 13: Restore your Modules

Go back into the Modules page and restore your modules. Navigate to the page by going to: Administer > Site building > Modules

Using the list of modules you made in Step 4, select the check box in front of each module to turn it back on. You should be able to select all the modules the first time through the screen. When you’re done, select Save configuration at the bottom of the screen.

Once the configuration has been saved, you should get a yellow box at the top asking about new releases. Select the check manually link in this box, to see if you need to update any of your modules.

If you get a message that says you need to update your modules, select the available updates link to see which modules need to be updated. If all your modules are current, skip to Step 15.

Step 14: Update your Modules

From the Available updates page, select the Download link for each module that needs to be updated. Copy the tar file into the modules/ folder for this particular site. For example, if it was the CCK module, you would do the following:

$ cd ~/Sites/drupal/6
$ cp ~/Downloads/CCK-6.x-2.1.tar.gz sites/drupal6.local/modules/

Now copy the existing module folder someplace else temporarily, and then unpack the new module.

$ cd sites/drupal6.local/modules
$ mv cck ~/Desktop/cck_backup
$ tar -xzf CCK-6.x-2.1.tar.gz

Back in the browser, check that your updates are all correct, by refreshing the Available updates page. Once you have all the correct versions of your modules, proceed to Step 15.

Step 15: Restore your theme

Return to the Themes page, by navigating to Administer > Site building > Themes

Make sure your theme is Enabled and selected as the Default, and then select Save configuration.

Step 16: Bring the site back online

Now we need to reactivate the site. Navigate to Administer > Site configuration > Site maintenance and set your site’s status to Online.

Then select Save configuration to reactivate the site. Log out and go back to the Home page, to verify that your site is functioning correctly. Navigate through some of your pages, to make sure everything looks OK.

Step 17: Repeat Steps 12-16

You’ll need to repeat Steps 12-16 for each site that you’re maintaining.

Note: Sometimes an update will change some of the underlying database tables. These changes can affect your modules, so you’ll need to make sure to run the status report on each site you have installed. You may need to run the database update script on each site, before you can reactivate the modules.

That should be all you need to do. Once you have checked through your sites, and everything looks to be running correctly, you can delete your backup folders.

Hopefuly you’ve found this tutorial useful. Let me know if you run into any issues when running through this tutorial.