Migrating from Joomla 1.5 to Joomla 1.6+
From Joomla! Documentation
Revision as of 12:31, 2 October 2011 by Joshua
With Joomla 1.6 officially released, there have been a lot of questions as to how to migrate or upgrade to Joomla 1.6 from 1.5. This guide will take you step-by-step through the general procedure of how to migrate to Joomla 1.6. Please read through all the material as this is not a light undertaking.
- 1 Before Upgrading
- 2 Upgrading
- 2.1 Download jUpgrade
- 2.2 Optional Testing Environment
- 2.3 Install jUpgrade
- 2.4 Enable Mootools Upgrade Plugin
- 2.5 Configure Options
- 2.6 Migration
- 2.7 Behind the Scenes
- 2.8 Check Your Joomla! 1.6
- 2.9 Backup Joomla! 1.6
- 2.10 Overview of the Rest of the Process
- 3 Going Live
- 4 How to Manually Upgrade Joomla
- 5 Troubleshooting
Don't let the numerical closeness of 1.5 and 1.6, mislead you. Joomla 1.6 took three years to develop and has been a major undertaking. Countless hours have been spent by many volunteers from around the world to put it all together. Although much of the code is the same from Joomla 1.5, much of it has been written from the ground up, and the changes are comparable to the changes from Joomla 1.0 to 1.5. Because the changes from Joomla 1.5 to 1.6 are so large and because of the massive effort put into getting Joomla 1.6 to where it is today, there is no core upgrade path, this is indeed a migration. In planned future releases of Joomla (which will be released every 6 months), such as Joomla 1.7, 1.8, etc, the changes from version to version will be more incremental and a core upgrade path is planned. Now that Joomla 1.6 is finally here and stable, a community initiative led by the developers of Joomla is turning towards jUpgrade (a 3rd party Joomla extension on the JED originally developed by Matias Aguirre) for help and to help. Many of Joomla's developers (who are all volunteers that freely contribute their time) are volunteering to put the finishing touches on jUpgrade.
jUpgrade allows you to migrate from Joomla 1.5 to 1.6. Lets get started!
Review the Requirements
Please, please save yourself (and possibly your clients) a lot of headaches and make sure that your server (and in the case of jUpgrade, your browser too) is up for the task. please review the technical requirements for Joomla! 1.6. Please review the requirements for jUpgrade as well.
Before You Get Started
Before you get started, there are a few things that you are going to have to check and/or think about:
- Is your Joomla 1.5 version up to date? The most up-to-date version of Joomla 1.5 is 1.5.23. If your version is not up-to-date, upgrade to 1.5.23 before migrating, especially if you are running Joomla 1.5.11 or lower.
- Do all your extensions have Joomla 1.6 native versions? At the time of the writing of this tutorial there are 108 available on the JED. Please note that jUpgrade is not currently able to upgrade Joomla 3rd party extensions, so those will have to be done via their respective upgrade procedures. This is however a work in progress.
- Have you modified any core files? Any changes that you have made to core files in Joomla will be lost so please be forewarned.
- Is there a Joomla 1.6 compatible template available from your template provider? If not, do you feel comfortable making the changes yourself? There are a couple good resources:
- Chad Windnagle's Joomla Community blog
- Chris Davenport's "Template Changes for Joomla 1.6" presentation
- Joomla's Docs Template Tutorial Please note that although jUpgrade is not able to currently upgrade templates, the developers are working hard at implementing the feature.
- Is your language pack available in Joomla 1.6? Find your Joomla1 1.6 Translation.
- Do you have folder or file permissions issues in your Joomla 1.5 installation?
- Do you NEED to migrate to Joomla 1.6? Joomla 1.5 is powerful and very mature. For many people there is not a need to rush into Joomla 1.6. Joomla will continue to support Joomla 1.5 for at least another year and three months, releasing security updates and bug squashing updates when needed.
- The two main features of Joomla 1.6 that makes it superior to Joomla 1.5 are: Access Control List (ACL) and nested categories. Gone are the days of simply having guests, registered users, authors, and editors, without being able to specify what they can and can't do in the frontend. Also, with 1.6 you can have more flexibility of organizing (and therefore displaying) your content with nicely organized categories within categories. No more being restricted to the section >> category structure. Those are all great things to have (especially the ACL), however, for many 1.5 users, it isn't needed. The main point is to decide for yourself.
- For a massive list of changes from Joomla 1.5 to Joomla 1.6, please see What's new in Joomla 1.6.
Backup, Backup, Backup
Skipping this part is perhaps the biggest mistake you can make. If you have a proper backup (or several) you can always revert back if needed. However, if you don't properly backup your site and something goes wrong, you are going to waste a lot of valuable time, and sometimes a lot money, getting things back to the way they were. So please backup!
Using Akeeba to backup
- Akeeba Backup produces a .jpa file
- The .jpa file contains all the folders/files and database files.
- The .jpa file also contains an installer
- Kickstart.php (from Akeeba) unpacks the .jpa file
- You then run the installer and install your site like a Joomla install.
- The installer has an option to change the configuration for restoring to a different location
After you create the Database for your Joomla download and install Akeeba, it can be download from Joomla extension directory. There is a link to full instructions there as well.
Download the latest version of jUpgrade. It is highly advisible, especially when development still is progressing, to always use the latest available version!
Optional Testing Environment
If you are really nervous by this point and your heart is beating fast, then you should probably set up a testing environment.
XAMPP is an easy-to-install package that bundles the Apache web server, PHP, XDEBUG, and the MySql database. This allows you to create the environment you need to run Joomla! on your local machine. The latest version of XAMPP is available at the XAMPP web site. Downloads are available for Linux, Windows, Mac OS X and Solaris. Download the package for your platform.
Important Note Regarding XAMPP and Skype: Apache and Skype both use port 80 as an alternative for incoming connections. If you use Skype, go into the Tools-Options-Advanced-Connection panel and deselect the "Use 80 and 443 as alternatives for incoming connections" option. If Apache starts as a service, it will take 80 before Skype starts and you will not see a problem. But, to be safe, disable the option in Skype.
As of August 5, 2010, XDebug has been updated (to version 2.1) which fixes some important bugs (for example, watching local variables for nesting functions). The latest XAMPP package (1.7.3) now includes this new version of XDebug. If you just want to update XDebug, you can download the latest module from . There is a handy website that tells you which XDebug binary you need, depending on your phpinfo() information here. To use it, you just copy the output of your phpinfo() display and paste it into the form on the site.
Installation on Windows
Installation for Windows is very simple. You can use the XAMPP installer executable (for example, "xampp-win32-1.7.3-installer.exe"). Detailed installation instructions for Windows are available here.
For Windows, it is recommended to install XAMPP in "c:\xampp" (not in "c:\program files"). If you do this, your Joomla! (and any other local web site folders) will go into the folder "c:\xampp\htdocs". (By convention, all web content goes under the "htdocs" folder.)
If you have multiple http servers (like IIS) you can change the xampp listening port. In <xamppDir>\apache\conf\httpd.conf, modify the line Listen 80 to Listen [portnumber] (ex: "Listen 8080").
Installation on Linux
Install xammp Open Terminal and enter:
sudo tar xvfz xampp-linux-1.7.3a.tar.gz -C /opt
(replace xampp-linux-1.7.3a.tar.gz with the version of xammp you downloaded). It has been reported that the MYSQL database of xampp 1.7.4 does not work with Joomla 1.5.22
This installs ... Apache2, mysql and php5 as well as an ftp server.
sudo /opt/lampp/lampp start
sudo /opt/lampp/lampp stop
starts/stops all the services
Test your xammp localhost server
Open your Browser and point it to
The index.php will redirect to
There you will find instructions on how to change default usernames/passwords. On a PC that does not serve files to the Internet or LAN then changing the defaults is personal choice.
Go to your Joomla backend. e.g. www.yoursite.com/administrator
Extensions >> Install/Uninstall
Browse >> Select com_jupgrade >> Upload File & Install
Enable Mootools Upgrade Plugin
- Go to Extensions | Plugin Manager
- Search for "System - Mootools Upgrade"
- Enable the plugin
It is important that this plugin is installed and that it has been set to enabled, as the proper functioning of jUpgrade depends on it.
As of jUpgrade version 1.1.1, support is present to migrate to Joomla! 1.6, Joomla! 1.7, and an old Molajo build. As well, for jUpgrade to be successful, you must configure your current table prefix prior to beginning the migration. The following are the options that can be configured with jUpgrade:
- Distribution - Select whether to migrate to Joomla! 1.6, 1.7, or Molajo
- Prefix for old database - Your current table prefix
- Prefix for new database - Your selected table prefix for your migrated site
- Skip checks - Skip pre-migration checks
- Skip download - Skip downloading the package (Note: Must have a package already downloaded to your temp folder or set this and Skip Decompress if set to yes)
- Skip decompress - Skip decompressing the downloaded package (Note: Must have a package already downloaded and decompressed to site_root/jupgrade if set to Yes)
- Keep original positions - Keep the currently defined positions for modules
- Enable Debug - Enable this to have messages displayed below the migration process concerning the progress, helpful if having issues
Components >> jUpgrade
Do not exit the screen until everything has finished loading. Scroll down to check if finished.
Please note that jUpgrade currently does not migrate templates, only default templates.
Behind the Scenes
As explained in the background information, the changes from Joomla 1.5 and 1.6 are quite significant. The fact that jUpgrade creates a new Joomla 1.6 installation for us is, in my opinion, pure genius. If the migration process was not 100% successful, your Joomla 1.5 is still perfectly intact and none of your users are affected. You have an opportunity to check out your site both in the frontend and the backend to make sure everything is up to par. So what actually happens? jUpgrade downloads the latest version of Joomla 1.6 for you to the jupgrade directory (which it creates) in the root folder of your Joomla 1.5 installation. It then extracts all the files from the download. Once extraction has completed, jUpgrade installs Joomla 1.6 and then proceeds to migrate your old database to the new Joomla 1.6 database which it has created. Your Joomla 1.6 site will be installed in www.mysites.com/jupgrade assuming that your Joomla 1.5 installation is in your html root.
Check Your Joomla! 1.6
Please do a full site review of your Joomla 1.6 installation and make sure everything is set up properly. Your Joomla 1.6 site will be installed in www.mysites.com/jupgrade assuming that your Joomla 1.5 installation is in your html root. Here is a general checklist to check:
- Templates - Work is currently being done on the template upgrade feature of jUpdate and it is not yet fully functional. Your module positions may have to be adjusted in module manager.
Backup Joomla! 1.6
If everything looks good to go, then let's backup the new Joomla 1.6 installation.
Overview of the Rest of the Process
Quick overview of what we are going to try to do now:
- Relocate our Joomla 1.5 installation to a subfolder as a "just in case".
- Relocate our Joomla 1.6 installation to the html folder.
'It should happen in this order' If you do it in reverse order, the Joomla 1.6 files will get mixed with the Joomla 1.5 files (many of 1.5 files will be overwritten) and you will have a big mess! Your site will likely still work, but it's a security ticking time bomb waiting to go off.
Next log onto your host's file manager (e.g. cPanel, Plesk, etc) or an FTP Client, however, preferably a file manager. The general procedure is (it should take about 30 seconds if you review the steps before you start):
- Create a subfolder (e.g. myoldsite) for the Joomla 1.5 installation in your html root, e.g. public_html/myoldsite
- Select all the folders (***except the jupgrade folder***) and files in the html root and move them into the Joomla 1.5 subfolder (e.g. myoldsite)
- Select all the folders and files in the jupgrade folder and move them to the html root
- Double check the frontend and backend
How to Manually Upgrade Joomla
If Jupgrade did not work out for you like many of us, don't worry there is an alternative method to upgrading. Unfortunately it is indeed a little tedious, but works perhaps 99% of the time. So just like the Jupgrade method, you will want to backup your database. This is mandatory even if everything goes 100% smoothly! Before upgrading you should check to make sure every extension you want is joomla 1.6/7 compatible. Also back up your directory files just in case and keep a list of the extensions you used.
Now onto the upgrade:
Step 1: Uninstall your old site including the database, files, and directories that are associated with joomla. Or if you would rather just test the upgrade, skip step 1 and create a new directory for your joomla 1.7 site.
Step 2: Install the new joomla which is done through a ftp or a cpanel. If you have no database associated with it, install a new database and user.
Step 3: Install your old site into a "sample" database. This is done because the prefix's need to be converted to work with joomla 1.7.
Step 4: Convert the prefix's of all the tables in the "sample" database which can be done using a script. Here is one that worked pretty well as seen on Nilop. Joomla 1.5 has the prefix of "jos" which you want to convert the prefix to "jml". So using your ftp install the php converter script onto the root of your site. It should be at the url Mysite.com/prefix.php which all you need to do is fill in the database information. After this you have all the tables nicely converted to the correct prefix of joomla 1.7.
Step 5: Install the components and other extensions you would have used before onto your new joomla 1.7 site. This is done first in order for non of your old database tables to be over written later.
Step 6: Export the database tables used from the extensions of your joomla 1.5 site as well as the users, content, and categories.
Step 7: Import the .sql file from your computer onto your joomla 1.7 database. It is possible that some extensions may have the possibility of changes to the sql tables when they upgraded there extension to joomla 1.7. If this is the case, it is recommended that you ask the developer of that extension for help with knowing what changes to the sql were made.
- first check, if you have php5 at least. (use phpinfo() or /usr/bin/php --version)
- Are you getting errors with the progress bar in Internet Explorer (Windows XP)? - Use Firefox: http://www.mozilla.com/en-US/firefox/
- Go through the Requirements and Before You Get Started sections above and double check everything!
- Report Bugs: http://matware.com.ar/foros/jupgrade.html
- Support: http://matware.com.ar/foros/jupgrade.html
How You can Contribute & Help
Creating an extension as significant as jUpgrade requires an enormous amount of time and effort considering the major structural changes between Joomla 1.5 and 1.6. Add to this the fact that during each release of Joomla 1.6 betas, the extension would have to be modified to work with the new changes between releases, and all of a sudden it's too hard for any one person to complete in a short period of time (especially when you are not being paid). With this being said, it's time to step up and make a difference, whether big or small. Have you profited from Joomla in the last year? Are you excited about the future of Joomla? Would you like to contribute back and show your gratitude? Now you can in this project! We, as part of the Joomla community, are calling on the entire Joomla community to help out in whatever way you can. You don't have to be a master developer, just go through this tutorial on a test site and if you come across any bugs, report it. If you know how to fix it, create a patch for it. If you are a master developer, step up to the challenge.
- You can report bugs here: http://matware.com.ar/foros/jupgrade.html
- You can volunteer and ask questions about volunteering here: http://www.matware.com.ar/forum/projects/jupgrade/volunteer-information.html