View RSS Feed

Behind The Code, with DrByte

How do I rebuild my site on the new version, instead of upgrading?

Rating: 118 votes, 4.69 average.

TL;DR / Executive Summary:

Are you looking for a quick way to understand best practices when upgrading your Zen Cart site? The easiest way to view it is as "a rebuild while keeping all the existing data."

This article contains 3 sections:
1. What an upgrade is, and what it is not.
2. An overview of how to rebuild a site using the new version, instead of upgrading.
3. How to upgrade while keeping the store live, and not losing any sales/customer/product data.

But first ... is your server compatible?
Check out the Server Requirements For Running Zen Cart, which lists each version and its compatibilities/requirements.

What is an upgrade anyway?

I've observed a number of misconceptions about what it means to upgrade a Zen Cart store from one ZC version to another.

Some people come at it from the angle of having used other frameworks that do things in different ways, or from any of a number of popular CMS systems that are architected differently perhaps with more of a plugin-style architecture where code or feature customizations are housed externally. In all of these cases the idea of "upgrading" comes with many preconceptions, and when the person discovers that upgrading in Zen Cart is done differently, they dig their heels in and object and complain that it should work the same as "XYZ" other software application.
Curiously, the same behavior is exhibited when someone comes to Zen Cart looking to set up a store or template, and discovers that ZC doesn't use Smarty or some other templating system that they're already familiar with, and they find that frustrating ... because they have to learn another way of doing things.

It's not wrong. It's just different.

The v1.x.x architecture of Zen Cart does "separate the business logic from the presentation logic", which thankfully allows most upgrades to have minimal impact on templates specifically. But when it comes to other core components, many times a number of core files must be touched. And while this in itself is not usually a big deal, it does get complicated when someone has installed a number of 3rd-party addons which have altered core code functionality. It's also particularly complicated when a new version NEEDS to change a LOT of files in order to integrate new features that have been in high demand. While v2 is being built to have more of a plugin architecture, the v1.x series requires a little bit of care when upgrading.

Anyway, back to the misconceptions...

In summary, a Zen Cart upgrade in version 1.x.x ...
  • is NOT merely a "replace these 5 files" exercise. (There are often 20-50 files affected)
  • is NOT a magical "click this button and you're suddenly on the new version". (There is no reliable "one-click upgrade" feature yet. Stay tuned for future versions where we plan to make this WAY easier!)
  • IS a quick rebuild of your site (quick meaning that it's way faster than when you built it the first time, since you already have a frame of reference)
  • DOES keep your existing data intact

The EASIEST way to conceptualize an upgrade is that it's an accelerated re-build of your site, using the new version, and keeping all your existing store data/configuration.

Now ... DON'T LET THAT word "rebuild" scare you! IT WILL NOT TAKE AS LONG to upgrade as it did to build your site in the first place!!
Maybe the first time you set up your store it took you a few weeks ... mostly because you were starting green, had no idea what a template was or where to put your graphics or product images, etc. But since your existing site is now a map of all the things you've done to customize your site, the rebuild is a much shorter exercise.

How do I rebuild my site on the new version, instead of upgrading?

Well, an upgrade *is* basically a rebuild. At least, that's what I find to be the simplest approach to take when upgrading.

In a nutshell, an upgrade is simply this:

a) make a list of all your existing customizations
- This includes all your addons/plugins, templates, custom features, etc
- There are handy file-comparison tools that help you quickly see any changes/additions/deletions you've made (such as WinMerge, Araxis Merge, Beyond Compare, etc)
- If you've already made good notes about your own customizations over the years, these notes will be very handy checklists/references for the next stage

b) re-make those on the new version
- installing updated addons/plugins designed for the new version, if necessary
- adding any small templating changes from the new version into a new copy of your existing template, or maybe using a new template altogether if that suits
- re-making your custom coding changes into the new version's files
- sometimes it might mean merging changes from the new version's core files into your own customized files, and/or vice-versa. This is no different than what you need to do when installing two addons that touch the same files, since their unique changes need to be merged together before they can be safely used together anyway.

c) upgrade the database to the new version
The zc_install script is used to do this in an automated way. Just a couple clicks to take care of keeping all your data intact and bringing its data structure up-to-date to work with the new version.

And of course, doing all of this in a TEST COPY of your site first, not on your live site directly, lets you ensure that everything is working and nothing is missed, before putting it all onto the live site. This way, when it comes time to actually touch your live site, you can do it in just a few minutes instead of potentially having your store down for much longer while testing/checking addons and customizations, etc.

How do I do an upgrade and still keep my live store running in the meantime?

You're a busy storeowner. You know you need to keep the business running while you safely test your upgrade, and you don't want to lose any data in the process.

The SMARTEST way to do that is this:

a) keep your live store running, as-is. With its own admin. Its own database. Its own folder of files on the server. Everything as-is.

b) build your new store in a temporary location. THIS IS ONLY FOR TESTING AND PREPARING FOR LIVE DEPLOYMENT.
This separate testing area will use a complete copy of your live site, in another subdirectory of your site, AND another database.
This is done following the main upgrade procedure as described in steps a), b), c) above, and in more detail at Upgrading - Detailed Instructions
REMEMBER: Any settings you adjust in your Admin, and any SQL scripts you run against your database will need to be re-done after "going live". SO TAKE REALLY GOOD NOTES so you know all the things you need to do again.
Same with any addons that you install. You'll need to re-run their installation process and configure them, since their setup won't be present in that database until you do. (See next step to understand these last 2 statements better.)

c) once you're ready to "go live", your temporary "new" store will be out-of-date because you'll have new customers, new orders, new payments, new products, etc in the live store.
So, you simply upgrade your live shop (since it has the most current data):
You can do this upgrade now on your live site BECAUSE you've already done all the testing and preparation in a temporary space.
This is the only scenario when you should upgrade your live site directly!

Pick a time when your live store is less-busy. This might be a typically "slow day", or an evening or a weekend, depending on your business. Follow these steps:

  1. Put your live shop down for maintenance (Admin->Configuration->Website Maintenance->first option, turn it on)
  2. Backup your live database for safekeeping
    It's also wise to backup all your existing php files/folders, images, etc ... everything in your hosting account.
  3. Replace all the Zen Cart php files/folders/images/everything in your live store with the new files (except the configure.php files which usually stay the same)
    Be sure to also delete any files that don't belong anymore.
  4. Upload all the files for the zc_install folder, and run zc_install/index.php and choose database-upgrade
  5. Re-do any admin settings and SQL changes, new addons/modules, etc relevant to the new setup.
    Refer to the list of notes you took while you did any additional customizing in your temporary site
  6. Turn off down-for-maintenance
  7. Do a test transaction to be sure checkout works
    And browse around all the pages to make sure things are working correctly.
  8. Do another backup of everything for peace-of-mind.
  9. Take a deep breath. :)

TIP: You *could* do a "trial run" of this whole upgrade process by making ANOTHER copy of your live site and doing
this upgrade to that site. Then you'll have either a checklist of additional things you'd missed, or you'll have simply the peace-of-mind of knowing that your live upgrade will go smoothly.
In fact, this is what I always do!

d) You can then delete your temporary site (files and database) because it's no longer needed. It was only ever used for "staging" to prepare yourself for the actual live upgrade of the live shop.

If you are considering changing webservers or hosting companies, do ALL of your upgrade activities BEFORE or AFTER the move. NOT DURING. If you confuse the picture by doing an upgrade at the same time, then you make it nearly impossible to determine whether your problems are the result of "moving" or a result of errors in "upgrading". So, always upgrade before OR after, but never "during" a move.
More about moving to another server here:

Submit "How do I rebuild my site on the new version, instead of upgrading?" to Digg Submit "How do I rebuild my site on the new version, instead of upgrading?" to Submit "How do I rebuild my site on the new version, instead of upgrading?" to StumbleUpon Submit "How do I rebuild my site on the new version, instead of upgrading?" to Google

Best Practices , Upgrading
Zen-Cart, Internet Selling Services, Klamath Falls, OR