Migrating Joomla 1.5 to Joomla 2.

5, a guided tutorial

With the release of Joomla 2.5 a few days ago, we begin to receive quite an influx of requests for guidance on migrating to Joomla 2.5 with JomSocial users and data intact. This tutorial will guide you with hopefully detailed steps on moving Joomla 1.5s data into Joomla 2.5, and steps needed to safely transfer JomSocial users and data into the brand new site. If you are not a JomSocial user and looking to only migrate Joomla 1.5, dont worry, the following instructions are perfectly valid as once you have completed Part 6, the migration is complete. We have tested 3 migration components listed in JED and will provide our findings for each of them. We are hoping that this guide will provide our dear users with a thorough and intimate understanding of how each migrator operates and choose the best option to suit your requirement.

The components are:

jUpgrade, Free for download (require registration) SP Upgrade, Commercial, 24.95 J2XML Importer, Free for download

Target demographics
1. Migrating Joomla 1.5 to Joomla 2.5 2. Migrating Joomla 1.5 to Joomla 2.5, and JomSocial data

Migrated Data
Joomla 1. Joomla Banners (jU, SPU) 2. Joomla Categories (jU, SPU, J2XML) 3. Joomla Contacts (jU, SPU)

4. Joomla Content/Articles (jU, SPU, J2XML) 5. Joomla Menu (jU, SPU) 6. Standard Joomla Modules (jU, SPU) 7. Joomla Newsfeeds (jU, SPU) 8. Joomla Users (jU, SPU, J2XML) 9. Joomla Weblinks (jU, SPU, J2XML) 10. Joomla Images (jU, SPU) 11. Joomla Templates (SPU) JomSocial 12. JomSocial Configuration 13. All JomSocial stored images/videos/avatars 14. All JomSocial data such as Events/Groups/Discussions/Profile information 15. In short, everything that makes JomSocial

Reality Check
Do you really need to migrate to Joomla 2.5 NOW? If it aint broke, dont fix it. Joomla 1.5 is one hell of a CMS. It is rugged and has endured a long series of updates that made it highly reliable, secure and yet, robust enough to handle most demand. These three qualities are hard to come by in a single web application. If your website is already flying high with Joomla 1.5, I would say give it a few months before attempting to migrate to Joomla 2.5 due to several inter-related reasons described below. However should you decide to give your website a total makeover, or to start afresh with a new mission, perhaps this is the perfect time to do it. Are all extensions on your Joomla 1.5 site compatible with Joomla 2.5? JomSocial is definitely compatible since day one, but how about the rest? Are those incompatible extensions critical to your sites functionality? Given the freshness of Joomla 2.5 (smells good), it is highly possible that some of them are not yet updated to meet Joomla 2.5s standards. Worse if the extensions are not even compatible with Joomla 1.6 or 1.7 because it may significantly delay support for Joomla 2.5. In light of these incompatibilities, do hold off migration for a while, and start urging respective developers to provide compatibility updates. Joomla 2.5 is fresh, very fresh. In my experience dealing with JomSocial support, some users tend to be excited with every new major version of Joomla, in such a manner that they spent more time upgrading (in this case, migrating) their site with the latest codes than providing a more meaningful usability or feature upgrades for site users. Yes, new features in Joomla core definitely excite us, but pondering over existing functionalities on your site, do you really need them? Joomla 2.5.0 is barely a week old. I would suggest you to patiently postpone until at least Joomla 2.5.1 before migrating to give your developers ample time to update their extensions which assure quality and to let things settle down. Good thing is, the release of Joomla 2.5.0 will see it being used by a much larger set of users than Joomla 2.5 Beta. This will of course result with more bugs being discovered by users due to such diverse systems configurations. Forget the extensions; is your template even compatible with Joomla 2.5? If you intend to have the same look and feel after the migration, it is essential to ensure that the Joomla

template that you are currently using for Joomla 1.5 has been updated to be compatible with Joomla 2.5. Should the template was designed by yourself, I am pretty sure you have already gone through this official Joomla documentation on upgrading a Joomla 1.5 template to Joomla 1.6/1.7/2.5. However should you rely on those awesome templates by Rockettheme, Joomlart, Gavick and others, it is best for you to contact them for an update.

Preparing Joomla 1.5 site for Joomla 2.5 migration

Requirements
1. The website must be at least on Joomla 1.5.21 (the minimum version that JomSocial supports) 2. A running JomSocial 2.4.2 or above (optional, if you wish to migrate JomSocial data) 3. An instance of Apache running locally / in localhost. The easiest method would be having XAMPP installed. 4. A mirror of the site runs locally. Guide on how to do that. 3. Some hugs, a steady mind and caramel frappucino, with cream please.

A responsible community manager will always follow a strict standard operating procedure before a major update is done to the website. The following steps form basic guidelines that we abide religiously while upgrading any site of ours. You may tweak it to suit your needs, requirements and system configuration. (Admittedly, these four points are directly taken from our JomSocial Upgrade guide, which holds as much relevance for Joomla migration too).

1. Plan ahead

A broken home will tarnish your reputation as a good host. Plan for the most suitable time to do an upgrade, for example in the middle of the night, when most people are asleep and when your users possibly at its lowest point. You may resort to Google Analytics to help you out in identifying the appropriate time & day for the upgrade.

2. Keep your users informed

Once a suitable time has been identified, always let your users know about this so that they are not surprised to see the site offline / in maintenance mode. This is also a good opportunity for you to engage your community and give them a voice to decide on proper time & date. Always assure your users that their information and data will be safe and secured. Do also provide with an estimate of how long the upgrade process would take. Depending on the size of your site, unique customizations, complexity of installed extensions and other variables, it could take from an hour to easily a day for a complete migration of the website.

3. Backups, Backups & Backup

I cannot stress this enough, a good webmaster always create a backup of his entire site and database from time to time, even when the site runs smoothly. Your last complete backup was months ago? Shame on you. The necessity to have a complete backup and multiple backups is critical while attempting any major upgrade to your site. Be it an installation of new components, or upgrade of existing ones, never forget to make a backup. One handy component that will truly ease your life is Akeeba, which automates creation of backups (files+database) on a predefined schedule. At the very least, consult your webhost to get a backup done for you. :)

4. Create a local test site

With the fresh backup files, create a mirror of your actual site in local development server. The purpose of having a separate mirror site hosted locally is for you to safely run migration trials without having to worry with any untoward damages on the live site. As the mirror site closely mimics the original Joomla system with the same template and extensions, you can easily detect possible clashes or upgrade errors during or upon the end of migration procedure. Fixing would also be easier and faster as it would have a much lower latency resulting with faster response time. If you are not sure on how to do that, please follow this official guide.

Comparison of Joomla 2.5 Migrators. In review: jUpgrade

We initiate this migration experiment by utilizing jUpgrade. jUpgrade is a popular migrator which has helped many to move from Joomla 1.5 to Joomla 1.6/1.7 not so long ago. It is frequently mentioned in numerous Joomla migration articles, in the Joomla Community blog, and also within the official Joomla Wiki.

How it works

jUpgrade is a component that has to be installed in your Joomla 1.5 site. During the migration phase, it will create a subdirectory within Joomla, for example domain.com/jupgrade and will actually install Joomla 2.5 within this directory while at the same time migrate Joomla 1.5 database into the new Joomla 2.5 structure. The same database will be used but using a different prefix for Joomla 2.5 (j17_# prefix) which is of course configurable at the backend. This method is pretty ingenious as it would mean that none of your live site files and database information is altered, completely out of harms way.

Setting it up
1. Make sure your local site is running well (guide). Depending on your level of comfort and proficiency, you may opt to do this migration directly on your live site. If you do, always

make sure a complete backup has been made. Consider this a warning. I myself am more comfortable running this locally. 2. Download jUpgrade from the official website (registration is required)

3. Install jUpgrade in the Joomla 1.5 website via Joomla Install/Uninstall area.

4. Go to Extensions > Plugin Manager, locate a plugin called System Mootools Uprade) and enable it. This plugin is required for jUpgrade to function. If you do not have this plugin, it means that you are using a very old version of Joomla 1.5. Upgrade to the latest Joomla 1.5.25 before proceeding.

5. Once enabled, go to Components > jUpgrade.

6. Go to Parameters and ensure the prefix for the old database is correct, and then submit your preferred prefix for the new Joomla 2.5 tables. Make sure you have set Yes to Skip template copy and Skip 3rd Party Extensions. 7. Save the configuration.

8. You may now start the migration by pressing the large Start Upgrade button. 9. Depending on your internet connection, system and localhost setting, it may take a few minutes to complete the task.

10. The screen will move from Checking > Downloading Joomla 2.5 > Decompressing package > Installing Joomla 2.5 > Upgrading Progress > Copying Templates if it is enabled > Copying images/media files > Upgrading 3rd extensions if its enabled > Finish. 11. If it stuck at any of the phases above, give it a good 10-15 minutes.

12. Once the migration is complete, head over to localhost/joomla15site/jupgrade to view the new Joomla 2.5 site. If you are running the migration directly on your live site, you may go to http://www.domain.com/jupgrade directory. 13. Be vigilant for possible errors, particularly with regard to user information and content structure. Go to Joomla 2.5s User Manager, Article Manager, Categories, Plugins and Modules, and play around with them. In User Manager, locate some users that you know and check whether their information is correct. Try updating some users, see whether they are saved. Poke here and there. :) 14. Migration is now completed! If you wish upload the migrated files into the live site, please follow Part 6 onwards.

Joomla 2.5 Migrator Review J2XML Importer

J2XML seems to be the cleanest way to migrate users and content in Joomla 2.5 with the use of XML files. I was almost led to believe this little component should be the focus of this migration tutorial, but I was disappointed at the end of my experiment to find out it has one very serious omission that may cause other migrated components to fail. If you wish to simply migrate Joomla Users and Content, and to start clean on Joomla 2.5 with new components (these components having fresh data), then this is the quickest path to achieve it. But if you wish to migrate data from other components such as JomSocial, Kunena, jReviews or others, you might want to avoid this migrator and rely on either jUpgrade or SP Upgrade instead.

How it works
J2XML consists of two separate components where by one has to be installed on the original Joomla 1.5 site to export information as XML files and the other one acts as an importer which has to be installed on the new Joomla 2.5 website. It is by far the cleanest of all those three migrators, and has the potential to be the best.

One drawback though, a big one that is. It seems that at the end of the migration phase, the component will actually modify userid, which means while the user information such as email, username and password is intact, his ID is not. This is a serious omission in my point of view, as having a different userid will directly cause a mismatch between Joomla and other third party components that map their database

information with the userid. In real world, it will cause JomSocial to assign streams, profile information and all other media to the wrong user, Kunena to assign permissions, forum posts, etc to different person, and other possible funky mishaps in other components due to a mismatched userid.

Setting it up
1. As mentioned, J2XML has the cleanest method of migrating Joomla User & Content. What you will need to do is to simply set up a Joomla 2.5 site, either as a separate directory within the live site (for example http://www.domain.com/joomla25) or create a local Joomla 2.5 site. 2. Download J2XML

3. Install J2XML in the Joomla 1.5 website via Joomla Install/Uninstall area.

4. Once completed, go to Plugin Manager, and enable XML-RPC - J2XML API and System J2XML plugins.

5. To export your users, simply go to Joomla User Manager, and you will notice two new options. Select all your users and export them away! An XML file will be created to store the exported information.

6. To export your articles, go to Joomla Article Manager, select all your articles, and export them. An XML file will be created to store the exported information. 7. With the export completed, now its time to import them into Joomla 2.5. Download J2XML Importer.

8. Install the component using Joomla 2.5 Installer.

9. Once done, go to Components > J2XML Importer

10. Pick the XML file that contain user information, and press import. 11. Repeat the procedure to import Joomla Articles. 12. Be vigilant on possible errors, particularly with regard to user information and content structure. Go to Joomla 2.5s User Manager, Article Manager, Categories, Plugins and Modules, and play around with them. In User Manager, locate some users that you know and check whether their information is correct. Try updating some users, see whether they are saved. Poke here and there. :) 13. You are now done! It is really easy, isnt it? If you wish upload the migrated files into the live site, please follow Part 6 onwards.

Joomla 2.5 Migrator Review SP Upgrade

Ok, remember when I said J2XML seems to be the cleanest? Well, SP Upgrade on the other hand seems to be the easiest. I was first reluctant to try this migrator given its cost (Euro 25), even more so when I notice how tiny the migrator is. At 13kb, it is certainly the smallest migrator, and component that I have ever encountered! Boy I was fooled. It packs a punch for its size. If you are willing to spend a bit, this migrator is certainly the one.

How it works
Contrary to the two other migrators, SP Upgrade does not require any installation on the original Joomla 1.5 site. The migrator, once installed on a fresh Joomla 2.5 site, will ask you for a direct access to the old Joomla 1.5 database, and will replicate it into the Joomla 2.5 database using core Joomla 2.5 functions. By utilizing the Joomla core functions the loaded components are built in the database, as if you create them manually, but keeps the same ids. That means 100% compatibility, stability and utilization of the new Joomla features unabashedly copied from its JED description.

Setting it up

1. A fresh Joomla 2.5 website has to be ready for deployment, on the same server either as a separate directory within the live site (for example http://www.domain.com/joomla25), or a separate directory within the local site. 2. Splash out some bucks for this migrator at the developer's site. 3. Wait for the confirmation email. Get some coffee if you will.

4. Once you have downloaded the migrator, install it through Joomla 2.5 Installer.

5. Head over to Components > SP Upgrade. The component is so small that it does not even have any options or pages to play around with!

6. Submit the requested information, and you are good to go! 7. Be vigilant on possible errors, particularly with regard to user information and content structure. Go to Joomla 2.5s User Manager, Article Manager, Categories, Plugins and Modules, and play around with them. In User Manager, locate some users that you know and check whether their information is correct. Try updating some users, see whether they are saved. Poke here and there. :) 8. You are now done! If you wish upload the migrated files into the live site, please follow Part 6 onwards.

Moving Joomla 2.5 from localhost to live site

Once you are satisfied, and have verified that the migrated tables are in working order, follow these steps to replace the live Joomla 1.5 with the newly migrated Joomla 2.5 website.

If the migration is done locally:

1. Make sure a backup or several backups of the live site have been made.

2. Completely erase all Joomla files in /public_html/ directory of the live site. Be cautious if you have several non-Joomla directories in it that you may require for other reasons.

3. Using your favourite FTP software, upload the entire content in /jupgrade folder of your local site into the live /public_html/ directory.

4. Once done, be sure to update Joomla 2.5s configuration.php, and update it to meet your new server setting. 5. Dont forget to also export the database for local site, and then import it into the livesite using PHPMyAdmin. 6. For more information on moving site from local to live, kindly view this Joomla documentation. 7. You are now done! Joomla 2.5 is now live! 8. If you wish to continue with migration of JomSocial information, please follow Phase 5 onwards.

If the migration is done on live site:

1. Make sure a backup or several backups of the live site have been made.

2. Completely erase all Joomla files in /public_html/ directory of the live site, but DO NOT delete the /jupgrade/ directory. Be cautious if you have several non-Joomla directories in it that you may still need them for other reasons. 3. Move all content inside /jupgrade/ directory into the main /public_html/ directory.

4. Once done, be sure to update Joomla 2.5s configuration.php, and update it to meet the new paths. 5. You are now done! Joomla 2.5 is now live! 6. If you wish to continue with migration of JomSocial information, please follow Phase 5 onwards.

Migrating JomSocial Data into Joomla 2.5

At this stage, it is assumed that Joomla User information has been successfully migrated to Joomla 2.5, and their information such as userid, username, password and email are intact. Again, userid MUST be intact! If your Administrator userid was 62 in Joomla 1.5, it has to be 62 in Joomla 2.5. This is the point where J2XML failed in our previous migration attempt. What a pity since it could have been one perfectly suited component for our needs. Before we get started, the first thing that you will need to do on the newly migrated Joomla 2.5 is to install JomSocial. Yes, thats right. This step is important for Joomla to capture JomSocial as an installed component, and for JomSocial to generate JomSocial Toolbar in the menu system. But hold on! Before installing JomSocial on Joomla 2.5, I would like to reiterate on one important warning. Please make sure that prior to installation; you have already installed JomSocial 2.4.2 (or above) on the Joomla 1.5 site. If you are using an older version, please upgrade to JomSocial 2.4.2. Why it must be JomSocial 2.4.2 (or above)? Well, only JomSocial 2.4.2 (or above) is compatible with Joomla 2.5. :D Once JomSocial 2.4.2 is installed on the Joomla 2.5 site, we are now ready to migrate JomSocial information from Joomla 1.5 to Joomla 2.5. JomSocial stores submitted data in three locations. 1. Database (user profiles, discussions, groups, events, photo information, any text) 2. Local files in /images/ directory (avatar, photo files, video files) 3. Amazon S3 (depending on your JomSocial setup)

Migrating JomSocial Database into Joomla 2.5

Heres an open secret. JomSocial database structure is exactly the same in Joomla 1.5 as in Joomla 2.5. They are both identical, which could only mean one thing, you can directly copy these tables into Joomla 2.5!

Using PHPMyAdmin (or any preferred software), go to the database and use the Export tab. Locate all database tables in Joomla 1.5 that start with jos_community_# prefix. All these tables belong to JomSocial. Export them. Once exported, save the file onto your desktop. Open up the database for Joomla 2.5, and make a backup of the entire database.

Subsequently locate all tables that start with [prefix]_community_# in Joomla 2.5, tick all of them, and select drop. PHPMyAdmin will delete all these tables. Dont worry, they are blanks and void. You will then import the tables that you have exported earlier into this Joomla 2.5 database, essentially merging the fresh Joomla tables with JomSocial tables that are filled with information.

To import the tables, simply head over to Import tab, and select the desired file.

In the event that imported Joomla 1.5 tables have different prefix (for example, jos_#) than Joomla 2.5 tables (for example, j25_#), you will have to rename these tables to ensure they match. I have also found a good tutorial on renaming tables using PHPMyAdmin here. You are now done!

Migrating JomSocial Files into Joomla 2.5

Migrating JomSocial files are really straightforward. You will only need to copy the entire /images directory in Joomla 1.5, and merge it with Joomla 2.5s /images directory. If you wish to selectively pick on JomSocial files, copy these directories: /images/avatar /images/files (new feature in JomSocial 2.6) /images/groupphotos /images/originalphotos /images/originalvideos /images/photos /images/videos

Migrating JomSocial Amazon S3 Files into Joomla 2.5

Assuming that JomSocial database has been imported correctly into Joomla 2.5, you do not have to do anything with Amazon S3 files. The database fields will correctly link them with the new Joomla 2.5 site.

Phase 6: Finalizing the Migration

Congratulations! Joomla 2.5 + JomSocial 2.4.2 is now deployed on your livesite! Take some time to reconfigure the extensions, templates and to ensure that all is in working condition. You might want to get some help from your users to report peculiar issues that they may have encounter after the upgrade. It is a community, after all. :) Phewww.. this is a really long post. Do let us know if we have missed anything or some clarifications needed.