Upgrading SilverStripe Installation to 2.4b

Posted by Jeremy on March 7, 2010

Tags: silverstripe, upgrades, silverstripe 2.4

Of the many things I've done this weekend, (lawn work, fiddling with site optimizations, packaging xulrunner applications for Macs, saving the planet...y'know, nothing too difficult) the thing that probably annoyed me the most, but had the biggest payoff (SEO-wise) was updating the site to SilverStripe 2.4. I apologize to anyone who may have stopped by (yes, I did see a number of 404's in the logs when I checked) this afternoon and gotten that message: my bad.

That brings me to the point of this post. Since I've upgraded this site a few times now, I'm beginning to see a pattern with SilverStripe upgrades. It's not something that is explicitly spelled out in the documentation for upgrades, and I'm here to shine some light on it: These upgrades take some time, and generally, they're less of an upgrade than a file merge into the new system. There's an order to the madness that'll make it take less time, but still expect it to take a while. So, without further ado, here's the methodology that worked the best for me (and yes, I tried several different ways; all in all, I killed 8 hours testing different ways to skin this cat). Below, I'm going to refer to the doc root often - if you don't know what your local  or remote server's document root is, please, don't try this. I'll be happy to step in and do your upgrade for you (it'll give me something to do on my endless string of dateless Saturday nights). Wow; I'm getting snarky.

1. Backup your database and download it to your local machine.
2. While you're crating your backup of your database, ZIP and download your current site to your machine.
3. Unzip your site somewhere convenient.
4. Install your site's database locally from the backup you just made.
5. Download the SilverStripe 2.4b1 package.
6. Unzip SilverStripe (tar xzf SilverStrip-v2.4.0-beta1.tar.gz from the command line).
7. Move the unzipped SilverStripe into your doc root.
8. Copy your existing site's mysite/_config.php to the new install's mysite directory.
   • You may need to correct your database settings for your local host - I've found it easier to comment out the old settings, and insert the new settings into the file. This way, when you move everything to your production server, all you have to do is delete your local settings and uncomment the production settings and you're good to go. Yeah, kinda elementary stuff, but yours truly is kinda air-headed sometimes, so I throw things out there, just in case you suffer from the same disorder.
9. Launch a browser and go to the fresh install.
   • At this point, all we're worried about is making sure the database connection works.
10. In the browser, log into the admin.
    • Trust me, if everything breaks, and you need to do a /dev/build/?flush=all to recuperate, you'll be glad you've already got a session, buck-o. It's worth noting at this point, if this upgrade takes you more than 20-30 minutes to do (and it probably will), go ahead and re-login to your admin periodically, especially if your local machine is greedy with session cleanup.
11. Copy your templates from your site backup directory to the new install in your doc root.
12. Copy the contents of your jsparty directory into mysite/javascript. The jsparty folder has been moved out of the doc root and subdivided into several different directories in 2.4. Yeah, I know, right? Take it up with the developers. For simplicity's sake, just move everything into mysite/javascript and you *should be ok*, if you follow the next step.
13. Check each of your template files for references to 'jsparty'. Change those references to 'mysite/javascript'. Unless you have javascripts that automatically include other javascripts (the way the Google Analytics script kinda does), you should have just avoided killing javascript functionality on your site. Note, you could, if you so chose, also include a line in your .htaccess file to rewrite jsparty requests to your mysite folder; something like Redirect 301 /jsparty http://[mysite.com]/mysite/javascript . You'll need to play with that; my experience is that correcting the problem is easier than figuring out .htaccess rules to go around the problem.
14. Now, run a quick ?flush=all on your local site and check to make sure your javascript works as expected.
15. Now begins the fun. Copy, in alphabetical order, your modules and widgets from your site backup to the new install folder. After you move each module or widget, run a /dev/build/?flush=all. AFTER EACH AND EVERY ONE. This makes troubleshooting that much easier. 
    • I flush whenever I run a /dev/build (because I like a fresh bowl..Allie McBeal, anyone? Anyone? No? Damn.) because it clears out the SilverStripe temp cache and avoids the possibility of any weird code remnants hanging around. Necessary? Probably not. Helpful, yes, it has been in the past.
    • You will (if you didn't correct it in your 2.3 install), with the Blog Module, get errors about the extraDbFields method. Open blog/code/TrackBackDecorator.php and change the method name to extraStatics (Deprecated in 2.3, removed in 2.4).
    • The full list of class name & method name changes is here. (Apparently "upgrading" is kiwi for "changelog summary", but there's helpful information there, none-the-less.)
    • Note: It may be quicker to check the SVN to resolve a problem with a module or widget than fixing the damned thing yourself (Twitter), so bear that in mind before delving too deeply into fix-it-landia.
16. Once you've moved everything over, try running the tests under /dev. I didn't have much luck because PHPUnit won't install cleanly under MAMP, but I ran enough to be confident that everything looked ok.
17. Go through your site on your local machine; once you've validated everything, zip it up.
18. Export your local database. It will have been changed with the initial /dev/build we did.
19. Create a new database on your remote server.
20. Import your the export you just created.
21. Move your remote doc root to something you can easily grab, in case of an emergency (i.e. public_html_old)
22. Create a new doc root and upload your files.
23. Remember to correct your mysite/_config.php for your new database name/credentials.
24. Set your cache and all of it's contents to 0777.
25. Send me a thank-you note.

Yes, compared to the paragraph and a half the procedure received on the SilverStripe documentation site, this seems like a helluva lot of work, however, this will get you a working, tested 2.4b1 site without much guesswork.

If you'd like us to do this for you, or have any questions, hit us up on the Contact Us page or leave a quote below!