Keeping your instance of Magento up-to-date with the latest available version is an important part of site maintenance and security. It’s also an incredible hassle. That being said, what follows is an overview of a straightforward Magento version upgrade without touching on any related issues such as third-party extension compatibility or theme overrides.
Step 1: Backup Your Site
This goes without saying, right? Under no circumstances should you ever attempt to upgrade a live/production storefront unless you want to have a really terrible day. So here’s my preferred method for knocking out a quick-and-dirty site backup:
Create Backup Copies of your Database and File System
Log in via SSH and make sure you’re in the root directory of your Magento instance. Create a backup of your database:
mysqldump -u USERNAME -p -h localhost DBNAME > backup.sql
You’ll want to replace ‘USERNAME’ with the database admin user name, and you only need to include the ‘localhost’ section if your server uses something other than localhost for its database server. Replace ‘DBNAME’ with your database name. After you hit return, you’ll be prompted to enter the password for this particular database user. Enter it and hit return again.
After the dump process is complete, you’ll see the backup.sql file sitting in your root directory along with the rest of your Magento file system. Now it’s time to back up the whole thing – file system and database dump together:
tar cvf backup.tar .
This will create a TAR archive of your entire Magento root directory, including the MySQL dump file you just created. It will take a few seconds to run, but then you’ll see the backup.tar file sitting in your file system.
Re-install your backups in a subdomain
Use your Plesk/cPanel/whatever admin to create a new subdomain, and move your backup.tar file into the document root. Create a new database to use with this subdomain, and then un-archive your file:
tar xvf backup.tar
Again, it will take a moment to run and then you’ll have a complete copy of your site’s file system in the subdomain. Next you’ll need to import the MySQL dump file into your new database:
mysql -u USERNAME -p -h localhost NEWDBNAME < backup.sql
Next you’ll need to hop into phpMyAdmin and update the core_config_data table to change the base URL and secure base URL settings to match your new subdomain. Lastly you’ll need to edit the app/etc/local.xml file to point this instance of Magento to your new database.
And just like that, you’ve got a backup where you can try the upgrade without having to worry about screwing up your production site.
Step 2. Prepare the Upgrade
Working within your test subdomain now, go ahead and download the latest version of Magento (CE v 126.96.36.199 as of publication):
Once it’s downloaded, go ahead and un-archive the .tar.gz file:
tar xvf magento-188.8.131.52.tar.gz
This will create a new /magento/ folder within your document root containing the full file system of the latest version of Magento. We’ll leave that there for a moment and make a few more preparations on the existing file system. You’ll want to flush your caches and delete the base theme files to minimize potential problems:
rm -rf var/cache/* var/session/* var/locks/* rm -rf downloader rm -rf app/design/frontend/base rm -rf skin/frontend/base
Next you’ll replace some of the files you just deleted with the corresponding files from the target version (in the /magento folder) as well as copying over the latest version of the mage shell:
cp -a magento/downloader . cp -a magento/app/design/frontend/base/ app/design/frontend/ cp magento/mage . chmod 755 ./mage
If you haven’t already done so, next you want to make sure that you set the preferred state of all Magento Connect modules to ‘Stable’:
./mage config-set preferred_state stable
Step 3: Copy the Target Version Files
And now the moment of truth! Using the commands below you’ll copy the target version’s file system into the root of your current Magento instance, overwriting duplicate files as you go. H/T to Duntuk for recommending that you repeat the copy command three times. There is no reason why it should take more than once, but I’ve definitely seen upgrades fail because some files from the target version failed to copy. This redundancy seems to prevent that problem.
yes | cp -Rf magento/* . yes | cp -Rf magento/* . yes | cp -Rf magento/* .
Now do a little bit of set-up and clean-up:
./mage mage-setup . ./mage sync --force ./mage install http://connect20.magentocommerce.com/community Mage_All_Latest --force rm -rf var/cache/* var/session/* var/locks/* php shell/indexer.php reindexall
Once the re-indexer is finished running, make sure that your system-wide file permissions are correctly set:
find ./ -type f | xargs chmod 644 find ./ -type d | xargs chmod 755chmod -Rf 777 var chmod -Rf 777 media
Lastly, visit the homepage of your test subdomain, and this completes the upgrade process. Give it a little while to load if necessary. Once everything loads as expected, log into the admin and check the version reference in the footer to make sure you are now running the target version. Put the site through its paces to make sure all functions perform as expected (ie place a test transaction, check transactional emails, create and edit products/attributes/categories and give the import/export function a trial).
Obviously the only files affected by the upgrade process described above are the Magento core code. If you are running any third-party extensions or are using any core template over-rides, you will need to take the necessary steps to ensure compatibility with your target version of Magento.
Had Enough? Get Yourself a Pro.
Upgrading Magento is a pain in the ass, even if you kind-of-sort-of know what you are doing. If you’re looking for a top-notch team of Magento professionals to manage your upgrade process for you, I can strongly recommend the team over at Atwix.com. I don’t have any kind of affiliate relationship with Atwix and I don’t get paid for recommending them; I just know them to be a terrific group of Magento professionals who will do a great job for you.
More Credit Where It’s Due
I credited Duntuk before, but his tutorial merits crediting again; I have gone through a lot of terrible, frustrating, and ultimately futile methods for attempting to upgrade Magento before, but the info from the Duntuk tutorial (simplified here using some of my preferred shell commands) provided the building blocks for my first successful Magento version upgrade. Thanks.