Revision as of 17:56, 24 April 2009

This Namespace has been archived - Please Do Not Edit or Create Pages in this namespace. Pages contain information for a Joomla! version which is no longer supported. It exists only as a historical reference, will not be improved and its content may be incomplete.

The migration from Joomla! 1.0 to 1.5 is handled for the most part automatically in two stages. The first stage is the export migration component for Joomla! 1.0 and the second stage is the import or migration phase of the Joomla! 1.5 installer. The system is automated due to a large number of changes that make data slightly incompatible between Joomla! 1.0 and 1.5, such as parameters for menus and content items. Whilst it is still possible to use a database dump to migrate, this is not advised as there will be data loss. This page aims to detail how to migrate from Joomla! 1.0 to Joomla! 1.5 with as much ease as possible.

Note: Read all of this document first and test before you attempt this in your production site to minimise down time.

Prerequisites

You will need a working Joomla! install, though using the latest available release of Joomla! 1.0 is always the best option. It is suggested that if you are using 1.0.13 you install Rob Schley's patch for admin sessions. As with everything you should take a full backup of everything before you start just in case something does go wrong. We advise that you do not destroy your 1.0.x install until you have completely finished migrating to 1.5 and are happy that things are working properly. Ideally you should complete migration using a testing system first before attempting it on your production system (e.g. either by using sites restored from backups or other replicas) and when deploying, separate your 1.0.x install from 1.5 (e.g. different database or at the least a different prefix).

If you're using a UTF-8 database please make sure that you have followed David Gal's Joomla! UTF-8 guide before you export from your Joomla! 1.0 site - this will make your dump file in UTF-8 format so when you come to the relevant part of the Joomla! 1.5 installation your encoding will be UTF-8.

If you aren't creating UTF-8 dump files then you are going to need to either have iconv installed on your server where you're installing 1.5 so it can automatically convert your dump file or convert it from what ever encoding it is presently into UTF-8 prior to migration. You can check if you have iconv by looking at the output of phpinfo for 'iconv', available in the help system of Joomla! (System -> System Info -> PHP Info under Joomla! 1.0 and Help -> System Info -> PHP Information under Joomla! 1.5). iconv is a relatively common extension that should be available in most situations, refer to either the PHP documentation or your hosting provider on how you can enable iconv.

Step 1: Downloading the Migrator component and installing it into your 1.0 instance

The latest version of the migrator component exists at the Pasamio Project's FRS site. At the time of writing the latest release is Migrator 1.2. Download the Migrator component to your system and then install it into the 1.0 install. This is done like any normal component install. There will be a Migrator entry in the Component menu option where you can access the Migrator.

Step 2: Installing Third Party Migrator plugins

The Migration system only handles the core system in its migration which means that if you want to include third party extension data from other tables you will have to install migrator plugins to handle the migration of this data. There are two types of plugins that are used: an "SQL" plugin which is a plain text SQL file and an "ETL" Plugin which is a bit of PHP that tells the migrator how to handle the data stored in tables (or in configuration files). This is done by selecting "Add Third Party Migrators", and then locating the plugin you wish to install and uploading the file. SQL files will be prepended to the output automatically and ETL plugins will be executed automatically. You can view a list of ETL plugins by clicking "List Plugins" in the main screen.

Step 3: Creating the Migration SQL File

Once you have installed any third party migrator plugins, you can select the "Create Migration SQL file" to begin the creation process. The system is designed to build an SQL file without causing a timeout on the server, so you may notice that the page automatically refreshes and displays status information. Eventually it will display a notification that the process has been completed and the SQL file will be available for download. Part of the SQL file generation involves the alteration of various fields to make them compatible with changes made in Joomla! 1.5, including the rewriting of mosimage tags.

Step 4: Installing Joomla! 1.5

Note: Create your new Joomla! 1.5 install in a separate directory and database to your existing install (or different prefix if you cannot create a new database). You cannot extract over the top of your 1.0 install, you have to create a new Joomla! 1.5 site. Alternatively, move your 1.0 install to a safe location and install into the empty directory 1.0 will have created. It is not a very good idea to install a new Joomla! 1.5 site over the top of your existing 1.0 site, it is better to test things in a seperate directory and progress from there.

If you can't install Joomla!, or Joomla! has already been installed, you can use the Migration Assistant in your 1.5 site. Note that beyond itself it will wipe out the 1.5 site's database back to a clean install and then do the migration. Any information that is in the 1.5 sites database will be deleted. The migration assistant is available at the same place as the Migrator, the latest version is Migration Assistant 1.5.2. There may be a later version, so check Pasamio Project's FRS site for any updates.

If you haven't done so already, take a full back up of your 1.0 site, including all of the filesystem and the database. Do not proceed without a backup.

The last phase of the migration is the installation of a new Joomla! 1.5 site. You need to install '1.5 into a completely new directory, you should keep this separate to your 1.0 directory. If you just unzip over the top of your existing 1.0 site, you will have issues with it finding an invalid copy of the configuration.php" file, so either move your original install or create a new directory. Complete the initial steps of the installation as per a normal installation. In the final step where you are prompted for the site name you are given the opportunity to initiate the migration process. Migration requires the generated SQL file to complete its operation, which might need to be uploaded to your new 1.5 site, there are two options for doing this:

HTTP Upload

FTP/SCP Upload

The first method, HTTP upload, is best for smaller SQL files that will fit within the upload limits of PHP. The alternative is to upload a file using either FTP, SCP or some other method of file transfer that your hosting provider offers. This is useful for larger SQL files that would normally not be permitted by PHP. To use the HTTP method, simply select the file like a normal component installation. To use the alternative upload method, upload the files into the installation/sql/migration folder and rename the file to be called "migrate.sql". If for some reason the migration fails you will need to reupload the SQL file for both methods, HTTP and FTP/SCP, as the file is altered through the migration process. The prefix for all migration dumps is "jos_", this should be placed into the provided text box. Once migration has been completed, enter in a site name (the site name cannot be migrated for technical reasons) and finish the installation.

Using either method the "/installation/sql/migration" folder and your temporary files folder (e.g. "/tmp") need to be writeable by the web user (e.g. "wwwrun", "www-data" or "apache"). The migrator will write data back to these locations as it updates the dump files.

Please note you also need to tick the "This script is a Joomla! 1.0 migration script" box as well before you migrate otherwise you will have issues with importing data.