magento logo

How to Upgrade Magento

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 1.9.1.1 as of publication):

wget http://www.magentocommerce.com/downloads/assets/1.9.1.1/magento-1.9.1.1.tar.gz

Once it’s downloaded, go ahead and un-archive the .tar.gz file:

tar xvf magento-1.9.1.1.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 755
chmod -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).

Customization Disclaimer

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.

Published by

Brian Lyman

Brian is the founder of Vale Studios, which is really just a stage name for what has been a great experience in freelancing. Brian is currently working under a dedicated contract for a terrific e-commerce retailer, but he uses this space to continue publishing ideas and reflections related to e-commerce, marketing, and Magento.

Leave a Reply

Your email address will not be published. Required fields are marked *