Note: while this article may seem very long, it’s only because I’m making every effort to clearly detail every step of my process for people who, like me, don’t have the Linux or php skills to easily understand what the heck everyone is talking about in the 6.10 upgrade articles and posts on drupal.org. In actuality, the upgrade itself will probably require less time than it takes to read this article. But DO read it, all the way through to the end, BEFORE you begin your upgrade.
Also note, you must be able to login to your site with full admin privileges for these steps to work; the user account”1” is the first user account created in a drupal installation, and it’s usually the admin account.
Do I REALLY Have To Upgrade? So Soon?
I set up my Drupal site on 1/23/09, so when I started getting dire warnings about an urgent security upgrade a month later I was both annoyed and concerned. Annoyed at having to do what seemed like a total re-install when I’d just gotten my new site customized the way I wanted it, and concerned about the potential to totally screw up my site in the upgrade process. However, since the upgrade includes a critical security fix, I knew the upgrade was not optional.
But I Don’t Know Anything About Linux or php, And I Don’t Have A ‘Development Sandbox’, Whatever That Is!
Most of the info I found on drupal.org on simplifying the upgrade process requires the site admin to write scripts or run them, and this won’t work for me since I don’t know anything about Linux commands and don’t have easy access to run scripts against my server anyway. Well, I found a way we Linux-illiterate people can complete the 6.9 – 6.10 upgrade with minimal site impact and no need to do the complete uninstall/re-install described in the upgrade.txt instruction file.
If You Haven’t Followed Drupal Best Practices, I Can’t Help You
First things first: While my Drupal install has been customized with contributed modules, autoresponders, custom logo, etc., I have followed Drupal best practices from day one by not making any modifications to the core software and keeping my customizations in the ‘sites/all’ folder of my installation. If you haven’t done likewise, the process I followed won’t work for you.
All Sites Are Unique: Your Upgrade Won’t Be Exactly The Same As Mine
While the steps I’m about to describe worked perfectly for me, every install and every server setup is different, so your mileage may vary. Finally, while the process I came up with was very easy and safe, it was also a little tedious. For me, tedious was far preferable to risky, and completely uninstalling and re-installing my site software seemed like VERY risky overkill.
Do You Really Have To Uninstall 6.9 Completely, Then Do A Full 6.10 Install?
In a word, no. From all I’d read on drupal.org I knew the 6.10 upgrade would only affect certain files and folders, and I also knew all my site’s content is stored in my site database, NOT the files and folders to be upgraded. I decided to limit my upgrade to identifying changed files and folders, backing up my current versions of those files/folders, and copying the 6.10 versions to my live server while leaving everything else alone. Here we go.
ONE TO TWO WEEKS PRIOR TO UPGRADE
Schedule your upgrade for the day and hour when site traffic is lowest (just check your site stats to decide), and post a notice on the front page of your site alerting your site visitors that the site will be taken offline for maintenance on the appointed day and time at least one week before you plan to do the upgrade.
You can optionally send out a blanket email to all your registered members too, but you should still post a notice on the site to notify both registered members and anonymous site visitors. This is especially important for new sites, since you’re still trying to build traffic and don’t want any of your site ‘regulars’ to find the site unexpectedly down and assume you’re no longer in operation.
A FEW DAYS PRIOR TO SCHEDULED UPGRADE
1) Download the 6.10 install package to your local machine; the download link is available on the front page of www.drupal.org when you login.
2) Unpack the 6.10 install package on your local machine in a location completely apart from your site setup and leave the window with the files in it open.
In my case, while I don’t have a Linux development sandbox or development server installed locally, I still have a local directory for my site which I use for purposes of developing and storing custom HTML pages and uploading files to my live drupal site. I unpacked the 6.10 install package entirely outside that directory on my PC, to avoid any confusion between the 6.10 files and the 6.9 files.
3) Open the file manager for your live, drupal 6.9 site in a separate window, in whatever way you usually do. I can do this via my locally-installed FTP program or via /cpanel >File Manager on my host server (my site is hosted by HostGator).
4) With the two windows open side-by-side, compare the date and time stamps on every file in your main installation directory (the one with the following folders: includes, misc, modules, openx, profiles, scripts, sites and themes) and each subdirectory to identify which files have changed in 6.10—and which ones haven’t.
Any file in the 6.10 window that has a date and timestamp older than the 6.9 version of the file you’re already running has not changed in 6.10. Conversely, any 6.10 file that has a more recent date or timestamp than your corresponding 6.9 file HAS changed.
Sorting the 6.10 files in reverse order of date/timestamp will bring all the changed files to the top of the list. I also found that printing out screenshots of the two windows helped a lot with this. When I identified a file that needed to be upgraded, I marked it with a highlighter on my printed screenshots for future reference when doing the actual upgrade. Alternatively, you can make a written list of changed files. Just make sure that you have some kind of written or printed file list to work with during the upgrade.
In my comparison I found the following file/folder differences between 6.9 and 6.10, but again, since your install isn’t exactly the same as mine, don’t just rely on my findings here. To be absolutely sure you’re catching every file needed for YOUR upgrade, you must go through the comparison process on YOUR files.
/www
The only files that changed in the main, /www directory were CHANGELOG.txt and install.php
/includes
actions.inc, bootstrap.inc, common.inc, database.inc, form.inc., install.inc, language.inc, menu.inc, module.inc, theme.inc
/misc
No changes to files in this folder
/modules
All modules except locale, openid, throttle and translation.
Within the module folders it was typically just the .info file that had changed, but I decided I would plan to go ahead and replace all my 6.9 /module folders with 6.10 folders rather than go to all the trouble of replacing individual 6.9 files in each /module folder with the changed, 6.10 versions. This was a safe thing for me to do because I have not made any changes or customizations in the /modules directory.
/openx
No changes to files in this folder
/profiles
No changes to files in this folder
/scripts
No changes to files in this folder
/sites
No changes to files in this folder
/themes
No changes to files in this folder
As you can see, the majority of 6.9 files are unaffected by the upgrade. When I saw this I felt more strongly than ever that I didn’t want to risk a complete uninstall/re-install of my site software.
AN HOUR OR MORE BEFORE SCHEDULED UPGRADE
1) Use your usual file manager or FTP client to download backup copies of all the 6.9 files you’ll be replacing with 6.10 files; store the backup copies in a new folder on your local hard drive, separate from your local 6.9 site directory (if you maintain a local 6.9 directory).
2) Familiarize yourself with the /admin/settings/site-maintenance page on your live 6.9 site. This is the page where you will take your site offline for the upgrade. You can go ahead and customize the ‘site offline’ message visitors will see during the upgrade now if you like, but DO NOT take the site offline yet.
UPGRADE TIME
1) Go back to /admin/settings/site-maintenance on your live site. If you haven’t already done so, customize the maintenance message site visitors will see while the site’s off-line. Take a deep breath and click the radio button that will change your site’s status from online to off-line, and save your changes.
2) Verify that your site is offline and your maintenance message is displaying to users. You can either open a window in a different browser program, in which you’re an anonymous site visitor, or you can logoff your live site and then re-load the home page of your site.
I have both Internet Explorer and Firefox browsers installed. I always login as site admin in one browser program, but remain an anonymous site visitor in the other. This saves me the trouble of logging out and back in every time I need to verify what anonymous site users will see. Besides, however unlikely it is, I can’t shake a nagging fear that once my site is off-line and I’m logged out as site admin, I may not be able to get back into the site’s admin account.
You may find, as I did, that the maintenance message only displays briefly before your site banner/logo loads on top of the message, making it unreadable. I elected not to bother with trying to fix this since I knew I’d scheduled my upgrade for the time when site traffic is lowest, and I didn’t plan to keep the site offline for long. I figured that fixing the problem probably would’ve taken longer than the entire upgrade.
3) Back up your site’s database, again, in a location separate from any local 6.9 install you may have. You may have to download a copy of the database via FTP, or your hosting company may provide backup tools. In the case of my host, HostGator, I can access backup tools via /cpanel and I’m given the option of backing up the entire site or just individual files, folders or databases.
Notice that unlike the 6.10 upgrade.txt instructions, I am not advising you to disable custom modules before proceeding. Since you’re not doing a full uninstall of 6.9 followed by a full install of 6.10, you’re keeping the site offline, and you’re leaving your browser window closed during the upgrade, it’s not necessary.
4) Close all other programs and windows on your local machine to free up system resources, including the browser window where you’re logged in to your site as admin, if it’s still open. Using your usual FTP client, upload the 6.10 folders and files you’ve previously identified as changed to your live, 6.9 installation, checking each one off your written list or screen shots as you go. If prompted to replace pre-existing files or folders on the server, answer “yes” to all.
IMPORTANT!! Don’t try to do this as a batch job: upload one folder or one file at a time! If the upload fails before everything is copied over, you will have a major chore to figure out which new files were copied over and which weren’t. You may find your site is irreparably broken and you’ll have to go through the full 6.9 uninstall followed by a full 6.10 install.
When you’re done, double-check the files and folders on your server to ensure you’ve uploaded all the files you previously identified as changed in 6.10.
5) Return to your live site and run update.php. You do this by entering the URL, http://www.yoursite.com/update.php, in which you’ve replaced “yoursite.com” with the name of your site.
6) You will be warned that it’s important for you to have backups of your site files and database before proceeding. If you’ve followed these directions, you have those backups and can safely proceed.
7) The update job doesn’t take long to run. When it’s finished, you’ll see status messages indicating updates have been applied.
8) If you don’t see any error messages following the update, your upgrade is complete and was successful. You can return to /admin/settings/site-maintenance to put your site back online and remove the maintenance announcement on the front page of your site. Finally, check the site as an anonymous user to verify everything is working as it should.
9) If you DO see error messages, I’m afraid I can’t help you debug them. However, I can tell you how to get your site back to where it was before the upgrade, and it’s easy.
Just copy your 6.9 backup files, folders and database back to your live server and run update.php again. Afterward, return to /admin/settings/site-maintenance to put your site back online, remove your maintenance announcement from the front page of your site, and check the site as an anonymous user as in step #8 above.
From there, your best bet is probably to schedule a new upgrade date and time, and follow the upgrade.txt instructions provided with the 6.10 package to the letter when you do that upgrade.
In my case, it only took about half an hour from the time I took the site offline to the time I was finished spot-checking the upgraded site.
Click here to read a related discussion thread on drupal.org.
Click here to share this article on Twitter!
April L. Hamilton is the founder of Publetariat and the author of From Concept To Community: How I Built An Online Community And Took It Viral In 25 Days With Little Money And No SEO. The book is available in trade paperback and Kindle editions on Amazon, and in various other ebook formats on Smashwords.