My God, we've been behind the 8 ball.
Seriously, did you realize that there have been something like 1.8 million Drupal releases since we last upgraded? Here we are sitting on Drupal 5.2 when the rest of the world is runnin' 6.6. Clearly, time to upgrade.
This afternoon, we decided to jump from Drupal 5.2 to Acquia Drupal, and this here article is the first of two that will document the process.
In this post, we're just talking about the actual Drupal upgrade process. No coding, no theming. Just updating Drupal to a version created in the last, oh, decade or so. Later, Jeremy will tackle updating your 5.x themes to work with 6.x.
Ok, so first thing's first. Before you do squat, there are a couple of files you'll want read.
First, check out the UPGRADE.txt file in your root Drupal directory. That bad boy is the Bible of your upgrade process, and you should have a pretty good idea of what's in there before you get going.
Likewise, if you're installing the Acquia flavor, get familiar with the
Acquia Getting Started with Acquia Drupal doc.
There are steps in there that aren't covered by a normal Drupal upgrade and, while this here post will talk about some of them, your own installation and upgrade experience could be drastically different. This post is just a supplement and, frankly, might not apply to certain installations.
We're also going a slightly different route in our migration. For instance, we're skipping the "Place the site in 'Off-line' mode" step because we're doing a copy-upgrade-rename thing rather than upgrading the live version of the site in place. That works for us, since we're a low traffic site and our comments are few and far between. You popular kids (God, I hate you guys...) might be better served putting the live site in Off-Line mode anyway, just so you don't lose any comments made while you're fiddling around with the copy.
Oh, and before you even start, make sure that there are 6.x versions of any modules you're using before you get too far into this. Wouldn't it suck to update your page only to find out that your favorite, my-site-depends-on-it module doesn't have a 6.x flavor? Yeah. It would.
So, without further ado, let's get rollin'.
Like I mentioned, we aren't going to just update our site in place. Frankly, the idea scares me. Instead, we're going to make a copy of our site and database and update that. After we've finished, we'll swap the copied-and-updated site for the live one, then crack open a cold one to toast our success.
And here's how we do it:
- Make a copy of current Drupal install directory.
cp -R <drupal directory> <copy directory>
2. Make a copy of the database for the upgrade.
Easy as pie:
- Create a new database using whatever means you normally would. My provider has a little control panel tool I use. Maybe you do it from the command line, maybe you use phpMyAdmin. Whatever. Just create a blank database.
- Create a new MySQL user and give it the necessary rights to the new database. Or grant those priveleges to your old user. Whatever makes you happy (I went with Option B, just because I like to minimize the number of users I have to manage. Up to you.)
- Export the data from your live database. I used phpMyAdmin for this. Just logon and click the Export button. Select your database and choose the SQL format. I left all the other options at their default values.
- Modify the export file to point to the new database. In my case, I changed the "USE" statement on line 22 of my dump to point to the new file. I also deleted the "CREATE DATABASE" line because my host makes me use their aforementioned tool for the process. Your mileage may vary.
- Import the data file. With phpMyAdmin, you just click the Import tab, browse to the file you want to import (the one you just exported/modified) and click Go. Done.
That's it. You should now have a copy of your DB. Of course, there are other methods. Feel free to share your fav in the comments.
3. Update the settings.php file in the new directory to point to the new database.
IMPORTANT. If you don't go to your settings.php file (/sites/default/settings.php) and edit the $db_url line, any changes you make from this point forward will happen on your live database. That could be very, very bad if things blow up on you. Edit that $db_url line to point to the new database name you created in the last step. If you created a new user, change that, too.
4. Confirm that you're using the new database, etc.
Ok, I'm anal about this kind of thing. I want to be 100% certain I'm about to jack with my copy rather than the real site. In my case, I created a new subdomain that points to the new directory, so when I browse to "http://nerdtest.nerdliness.com," Apache serves up the files in my ./nerdtest directory instead of my original ./nerdliness one. Make sense?
How you do this will depend on your host. In my case, I get a handy little control panel with a "create subdomain" link that takes care of the Apache and DNS changes. If you're hosting yourself, you might have to make your own httpd.conf and DNS record changes. Or if you have another host, you'll need to check with them. Sorry, but there are as many different steps for this part as there are hosting providers.
Anyway.
After creating the subdomain, browse to your site copy and make a small change. Maybe leave yourself a comment or make a test post. Whatever you do, make sure it only appears on the subdomain and not on the original.
5. Get your modules in order.
Ok, we've been bad. We had a ton of modules chillin' in our /modules directory instead of in the /sites/all/modules 'hood where they belong. The longest part of this process involved moving those user contributed, third party modules into their correct location.
The Acquia guide has a good list of core Drupal modules that need to stay in the /modules directory, but it isn't all-inclusive. Before you start moving all the modules from /modules to /sites/all/modules, make sure you're moving the right ones. Check out the docs online for the full list. In my case, I just had one window opened to my Drupal Admin page and made sure I didn't touch any modules that were listed under the Core - Required or Core - Optional headings.
Make sure you check out your site after making all thes moves, just to be safe. Would hate to try to update after you've already moved out some core module that you shouldn't have touched only to find that nothing works right.
6. More module maintenance...
Acquia includes fancy-pants versions of some important modules, so you need to 86 any versions you have installed already before you do The Upgrade. Make sure you deactive and remove them before you continue. There's a full list of modules in the Acquia Getting Started guide, starting on Page 24, and it includes stuff you're almost certainly using (CCK, anyone? How 'bout Views?)
Note: there's a special case around the Printer-Friendly Pages and Filefield Meta modules. Didn't apply to us, might apply to you. Make sure you RTFAcquiaGettingStartedGuide, page 25 ("Special Cases: Printer-Friendly Pages Module and Filefield Meta Module").
7. Download/unpack the Acquia Drupal goods.
Browse to http://acquia.com/downloads and download the current "Update Existing" version. Copy that bad boy over to your web server and untar it.
8. Update!
Now the real fun starts.
First, since we downloaded the "Update Existing" version of Acquia, the directory created when we untarred that file is missing some key elements from our actual site. We need to copy those over before we do anything else. Basically, we need to copy our .htaccess and robots.txt files, our entire sites directory (and its contents), as well as any other customized files that live outside those folders.
cp <copy directory>/.htaccess <acquia directory>/
cp <copy directory>/robots.txt <acquia directory>/
cp -R <copy directory>/sites <acquia directory>/
9. Rename your directories
Now that our customized files are in the Acquia untar directory, we just need to rename our copy directory to something new, then rename the Acquia directory to the same name our copy directory used to have.
Good God, that doesn't make much sense, does it?
Ok, so say we untarred the Acquia files to a directory called "acquia," and our old working Drupal directory was "nerdtest." Now, we're going to rename "nerdtest" something like "old_nerdtest," then rename "acquia" to "nerdtest." Got it?
mv <copy directory> <new name for copy directory>
mv <acquia directory> <copy directory>
10. Run the update.php file
Just browse to the /update.php file on your site and do what it says.
11. Pray.
12. Check for errors
You should get a progress report immediately after the update that mentions any specific errors. Also check the Status Report page (/admin/reports/status). Make sure you follow any advice given on this update results page.
In our case, we had a couple issues. First, the Status Report mentioned that the "files" directory didn't exist. Sure enough, we'd forgotten to copy that over from our previous install back in step 8. Easily fixed with a little "cp -R <new name for copy directory>/files <copy directory>" action.
Second, we noticed this blurb:
Updates for CCK-related modules are not run until the modules are enabled on the administer modules page. When you enable them, you'll need to return to update.php and run the remaining updates.
Piece of cake. All we had to do at that point was go into the Administer Modules page, enable those CCK modules, then rerun the /update.php script. No problems.
13. Update and reactivate modules
You'll probably find that several modules you used with 5.x have big red X's next to them in the Admin page now. Yeah. Sucks, huh? Probably should have checked for newer versions of those modules ahead of time, right? Like we warned you about before you even started?
Anyway, now's the time to download and install those newer versions. You know how. And this time, remember to put them in /sites/all/modules.
15. Bring the site "On-Line"
We didn't put ours in Off-Line mode, but if YOU did, make sure you bring it back up.
16. Test.
Browse around, check everything out. If it all looks good, fantastic! If not, well... Can't really help you there. Our's went just fine. :)
Ok, maybe "fine" is a bit too... um... Pollyanna of a word. We had some issues with some permissions (anonymous users couldn't see content for some reason) and formatting (former header/footer blocks ended up in the sidebar), etc. But all of those were things that were pretty easy fixes. Nothing major.
If YOU have something major come up though, leave comments. We (or someone reading this) might be able to help.
17. Go live!
If everything looks good, it's time to bring it live.
Remember that we did this with a copy of the site, so we need to change a couple directory names. It's really the same exact process as in step 9, just with different directories:
mv <drupal directory> <some other name>
mv <copy directory> <drupal directory>
Also, if you put yours in Maintenance Mode, remember to disable that.
And that's pretty much it. Really not too difficult. I'm sure we'll continue to find little pieces here and there that need some massaging every now and then, but overall the process was relatively painless.
Now if we could just get Jeremy to update our old theme... Not like he's got a full time job and a newborn daughter keeping him busy or anything...
