This is the third in a four-part series of articles covering the current market and development status of the recent landmark release of the Joomla! v3.x content management system. An earlier version of this article was originally commissioned and published by on 17 May 2013.

The remaining articles in the series are:

Part 1: What's new in Joomla! 3.x?
Part 2: Current state of the Joomla! market, and a Joomla! 3.x base build
Part 4: Ready for production use

In this third article, we look at a case study of a Joomla! 3.x site migration.

Migrating the Psicom main site

I recently helped myself to a big plate of my own dog food, and migrated  this site to Joomla! 3.x. You are looking at the result right now.

I had a few options to upgrade the site and it took a couple of attempts to get the job done. I learned lessons along the way, which I am pleased to be able to share with you now.

Auto-upgrade the site from the Joomla! STS repository

Joomla! 2.5 provides an obscure means of automatically update a site from v2.5.x direct to the current v3.x.

Please be warned: this option is provided for use by experienced developers, and experimenters. It is not intended for casual use by site builders who are hoping for a lazy way to migrate Joomla! 2.5 sites. It definitely should not to be used to update production sites, as you will see.

The update option can be found behind the Options button tucked away at the top right on the Joomla! Update component. It looks like this:


Joomla update options


This configuration option for the Joomla! Update component allows you to set which repository is used to provide product update images for automatic updates of your Joomla! system. By default this option is set to the Long Term Support product repository, and this is also the recommended setting.

As I explained in Part 1 of this series, Joomla! 2.5 is an LTS release (a Long Term Support release), while Joomla! 3.x is an STS release (a Short Term Support release). So to get your Joomla! 2.5 installation to update itself to the current 3.x.x release, you only have to tell it to get its updates from the STS update repository rather than the LTS repository.

The next planned LTS release will be version 3.5, scheduled for September 2013. If you leave your Update Server set to the LTS repository, it will continue to get its updates from 2.5.x code and ignore any version 3.x.x or 3.1.x updates, until the next LTS release comes out. That will be an interesting horizon.

In theory, any 2.5.x sites that are automatically updated from the LTS repository after the release of v3.5 may be automatically updated to the new version by accident. As things stand right now, that may be a disaster for owners of Joomla! 2.5.x sites who are not prepared for the change, because the update to any 3.x version of the Joomla! CMS is not likely to be seamless, as you will see. No doubt we will hear more about this as Joomla! 3.5 approaches its release.

Back to our story. I wanted to test how this update method would work on a real site, so I proceeded like this:

  • I verified that Joomla! 3.x versions of all the components I am using on my site were available, and I updated my site so that it was right up to date with only 3.x.x compatible components.
  • I took a backup of my site with Akeeba backup (as recommended in my previous article in this series)
  • I restored the backup as a new site on my development machine
  • I flipped the Joomla! Update switch to the STS repository, as shown above
  • I cleared caches and let Joomla! Update check its repository. Sure enough, it said that there was a v3.x.3 update available. I then ran the update.

The Joomla! Update component detected and downloaded the current Joomla! 3.x.3 install package, and it unpacked all the new site files without incident. Then it started the database updates, and produced ... a white screen. Backing up to the administrator console revealed this message:

0 - An error has occurred.

SQL=ALTER TABLE '#_users' DROP KEY 'usertype';

Return to Control Panel

Of course, that's a system error. It has nothing to do with any third party components that were installed. So I hit the link to return to the Control Panel, and the system finally threw a 500 Internal Server Error. It had died.

So what next? I could find and fix the internal system error and then carry on. Or I could restore a new copy of my 2.5.x site, modify the Users table so that the ALTER SQL would succeed instead of failing.

But if an update to a fundamental table like the Users table failed, I could expect further, and perhaps more subtle failures, so the upgraded system might continue to throw problems indefinitely. Also, many Joomla! site builders would have trouble finding and fixing these system errors in the first place, so this was not an upgrade method that I could recommend to the community.

I concluded that this approach was probably not going to result in an upgraded system that I could trust.

With apologies to various members of the Joomla! community, an automatic update of a stock-standard native system from 2.5.x to 3.x.x may work but it is of very little use, since it would be simpler and safer to achieve the same result by just downloading a current 3.x.x release and installing it from scratch. It is possible that in time other capabilities of the Joomla! Update component may become useful or important, e.g. updating to a test or custom version of the CMS.

But right now, it is not safe to upgrade your Joomla! 2.5.x site to v3.x.x using the standard Joomla! Update component. It just isn't that simple.

Install Joomla! 3.x base build and rebuild the site

Apart from the automatic Joomla! Update (which did not work for me), there are not many upgrade options. There are a couple of useful migration tools for handling upgrades from Joomla! 1.5.x or 2.5.x to 3.x.x:

Both of these tools are similar insofar as they require a new, empty Joomla! 3.x site to be installed as the target site, and they extract data from the source database (a 1.5.x or 2.5.x site) and import it to the target site. However, the components differ in several ways:


  • Performs a direct data mapping and transfer from the source database tables to the target database
  • Transfers the great majority of site content and structure (menus, modules etc.)
  • Limits transfers of site files to images and core template files

Jinfinity Migrator

  • Is installed on both the source and target sites
  • Uses exporter and importer plug-in functions to extract/import data and objects to/from CSV files
  • Does not transfer contacts, web links, news feeds, banners or modules from 2.5.x (but it does handle 1.5.x modules)
  • Transfers site files and folders
  • Can be extended with custom-built exporters and importers to handle migration of third-party components
  • These tools can save a lot of time in upgrading sites to Joomla! 3.x.x, particularly on large sites with lots of content and elaborate structure.

In my case, I migrated my content, made some revisions and adjustments, and had my new site in production in about four hours.

Template options

The finishing touch (for now at least) was the site template. I've written a little about templates in part 1 of this series. For my purposes, I had three options:


The new Bootstrap template named Protostar that ships with Joomla! 3.x supports the new Joomla! 3.x UI and platform, and it ran all the components in my base build system flawlessly. I am convinced that site designers with good CSS skills can achieve excellent results by cloning the Protostar template and adapting it to customer design requirements.

Commercial templates

The major commercial template providers are already well down the road with Joomla! 3.x templates. Many outstanding, attractive templates are already available for many types of sites. However, not all of them offer full support for Bootstrap and the related JUI technologies. The significance of this factor may vary with the circumstances and needs of specific sites.

A more important consideration is whether your template supports all the extensions you want to use in your site build, and particularly the major business components you may be using. In my case, I had minor support problems with one of my preferred components, but I found workarounds without much trouble.


I've used Artisteer for a few years as my default method of template development. The latest version of Artisteer ( now supports Joomla! 3.x. But at this stage Artisteer templates do not use Bootstrap features at all. I expect that Artisteer will support Bootstrap in time.

The same component that misbehaved with commercial templates also showed some minor problems in the Artisteer template, but once again I found workarounds.

In the end, for my site upgrade I adopted Protostar as the foundation of my template, modified and compiled some LESS code and hey presto! a sleek new site.

Next: Joomla! 3.x in production