Author: channa Date: Mon Sep 15 07:18:53 2008 New Revision: 21833 URL: http://wso2.org/svn/browse/wso2?view=rev&revision=21833
Log: Update migration guide. Added: trunk/mashup/java/xdocs/images/extraction_util.png (contents, props changed) trunk/mashup/java/xdocs/images/import_util.png (contents, props changed) Removed: trunk/mashup/java/xdocs/images/migration_result.png Modified: trunk/mashup/java/xdocs/migrationguide.html Added: trunk/mashup/java/xdocs/images/extraction_util.png URL: http://wso2.org/svn/browse/wso2/trunk/mashup/java/xdocs/images/extraction_util.png?pathrev=21833 ============================================================================== Binary file. No diff available. Added: trunk/mashup/java/xdocs/images/import_util.png URL: http://wso2.org/svn/browse/wso2/trunk/mashup/java/xdocs/images/import_util.png?pathrev=21833 ============================================================================== Binary file. No diff available. Deleted: trunk/mashup/java/xdocs/images/migration_result.png URL: http://wso2.org/svn/browse/wso2/None?pathrev=21832 Modified: trunk/mashup/java/xdocs/migrationguide.html URL: http://wso2.org/svn/browse/wso2/trunk/mashup/java/xdocs/migrationguide.html?rev=21833&r1=21832&r2=21833&view=diff ============================================================================== --- trunk/mashup/java/xdocs/migrationguide.html (original) +++ trunk/mashup/java/xdocs/migrationguide.html Mon Sep 15 07:18:53 2008 @@ -17,7 +17,7 @@ ~ limitations under the License. --> <meta http-equiv="content-type" content=""> - <title>Data Services</title> + <title>Migration Guide</title> <link href="css/mashup-docs.css" rel="stylesheet" type="text/css" media="all"> </head> @@ -25,7 +25,7 @@ <body style="direction: ltr;"> <div id="main-content"> -<h1>Server Migration</h1> +<h1>Migration Guide</h1> <p>This document describes how you can migrate from an older version of the Mashup Server to a newer version. Steps for reverting to a previous version @@ -55,115 +55,145 @@ old installation into the now empty 'database' and 'scripts' directories of the new installation.</li> <li>Start the new server. You will not be requested to provision the new - installation as the previously created admin account will be active on - the new server. </li> + installation as the previously created administrator account will be + active on the new server. </li> </ol> <h1>Upgrading from a 1.0.x installation to a 1.5.x Installation</h1> -<p>Migrating a 1.0 installation of the Mashup Server to a 1.5 requires that -data be exported from the older version of the Mashup Server and imported -into the new version. The steps below describe how the migration tools can be -setup and used to perform the data migration.</p> +<p>Migrating a 1.0.x installation of the Mashup Server to a 1.5 requires that +data be exported from the older version of the WSO2 Mashup Server and +imported into the new version. The steps below describe how the downloadable +'MigrationTool' can be setup and used to perform the data migration. </p> + +<h2>Getting the Migration Tool</h2> + +<p>You can download the MigrationTool.zip file containing the binaries, JSP's +and configuration files required to perform the migration from <a +href="https://wso2.org/repos/wso2/people/channa/migration/MigrationTool.zip";>here</a>. +Extract the contents of the zip file and perform the steps below to migrate +your Mashups and MetaData from your 1.0.x installation to your a 1.5.x +installation.</p> -<h2>Step 1 - Exporting Data from the 1.0 installation</h2> +<h2>Performing the Migration Using the Migration Tool</h2> -<h3>Getting the Migration Tool</h3> +<p>This document assumes you have installed, but not provisioned a WSO2 +Mashup Server 1.5.x on the same system that is running the WSO2 Mashup Server +1.0.x. The installation root directories of your Mashup Server 1.0.x, Mashup +Server 1.5.x will be referred to as 'Mashup 1.0 Home' and 'Mashup 1.5 Home' +respectively. The extracted contents of the MigrationTool.zip file are +assumed to reside in the 'MigrationTool' directory.</p> -<p>User, Mashup and Activity information is extracted saved into the Mashup -Home directory by the 'MigrationTool' java class. The source code for this -class can be downloaded, included in the 1.0.x source and built into a -mashup-core java archive, or a wso2mashup-core-1.0.x.jar with the migration -tool included can be downloaded. In either case the jar file should be copied -into the MASHUP_HOME/lib directory. Along with this, the migrate.jsp page, -which invokes the migration tool, needs to be downloaded and saved in the -'/lib/tomcat/webapps/ROOT' directory.</p> - -<h3>Running the Migration Tool</h3> - -<p>Start up the server, once you have copied the jar file and JSP into the -relevant directories.</p> - -<p>Call the migration tool by accessing the [Mashup Server URL]/migrate.jsp -page. If you access the mashup server at https://localhost:7443/, you can -start the serialization by accessing https://localhost:7443/migrate.jsp on -your browser.</p> +<h3>Step 1 - Exporting Data from the 1.0.x installation</h3> -<p>When the migration completes, the followiing page will be displayed, -indicating the location of the exported data files.</p> +<p>1.1. Move the 'wso2mashup-core-1.0.2.jar' file out of the 'Mashup 1.0 +Home\lib' directory.</p> -<p><img alt="Migration Output" src="images/migration_result.png" width="900" -height="145"></p> +<p>1.2. Copy the 'wso2mashup-core-1.0.x-withexport.jar' file from the +'MigrationTool\export' directory to the 'Mashup 1.0 Home\lib' directory.</p> -<p>The migrated_metadata.xml contains serialized user information and -metadata for all mashups including tags, comments and ratings entered by all -users.</p> +<p>1.3. Copy the 'extract.jsp' file from the 'MigrationTool\export' directory +to the 'Mashup 1.0 Home\lib\tomcat\webapps\ROOT' directory.</p> -<p></p> +<p>1.4. Start the 1.0.2 Mashup Server and access the extract.jsp page +(typically at <a +href="https://localhost:7443/extract.jsp";>https://localhost:7443/extract.jsp</a>).</p> -<h2>Step 2 - Setting up the New Mashup Server</h2> +<p>1.5. The follwing page should be displayed:</p> -<h3>Installation</h3> -Install version 1.5.x of the WSO2 Mashup Server in a separate location, -making sure the previous version of the Mashup Server is shut down but not -uninstalled. Do not start the new server yet. +<p><img alt="Extraction Confirmation" src="images/extraction_util.png" +width="50%"></p> -<h3>Setting up the Migration Initializer</h3> +<p>1.6. Shut down the 1.0.x Server.</p> -<p>The 'Migrationinitializer' java class re-creates the users registered in -the old instance of the Mashup Server in the new instance and also restores -the user profile and mashup metadata. The source code for this class can be -downloaded, included in the 1.5.x source and built into a mashup-core java -archive, or a wso2mashup-core-1.5.x.jar with the migration tool included can -be downloaded. In either case the jar file should be copied into the -MASHUP_HOME/lib directory. For the initializer to locate the old instance of -the Mashup Server's user database, the old_database_settings.xml file also -needs to be downloaded, copied into the MASHUP_HOME\conf directory and -updated with the location of the Old Mashup Server's WSAS database. Finally, -the import.jsp page, which invokes the migration initializer, needs to be -downloaded and saved in the '/lib/tomcat/webapps/ROOT' directory.</p> - -<h3>Metadata Migration</h3> - -<p>Copy across the user script directories including all contents, from the -MASHUP_HOME\scripts directory of the older server to the MASHUP_HOME\scripts -directory of the new server. Dd not copy across the system and samples user's -script directories as you will lose updated scripts shipped with the new -version of the server.</p> +<p>1.7. Delete the 'wso2mashup-core-1.0.x-withexport.jar' file from the +'Mashup 1.0 Home\lib' directory and restore the 'wso2mashup-core-1.0.2.jar' +file.</p> -<p>Copy across the the migrated_metadata.xml file from the MASHUP_HOME -directory of the old Mashup Server to the MASHUP_HOME directory of the new -installation.</p> +<h3>Step 2 - Importing Data into the 1.5.x Installation</h3> -<p>Start the Mashup Server. The users will be re-created and the mashups will -be deployed.</p> +<p>2.1. Move the 'wso2mashup-core-1.5.1.jar' file out of the 'Mashup 1.5 +Home\lib' directory.</p> -<p>Call the import.jsp by accessing the [Mashup Server URL]/import.jsp page. -If you access the mashup server at https://localhost:7443/, you can start the -import process by accessing https://localhost:7443/migrate.jsp on your -browser.</p> - -<h3>Provisioning</h3> - -<p>The typical provisioning of the server, including the setup of the -administrator ID, can be completed now. Please refer to the installation -guide for details on provisioning.</p> - -<h3>Log Migration (Optional)</h3> - -<p>The activity logs exported from the old instance of the mashup server can -be restored if required. If this step is not completed, you will have an -upgraded Mashup Server with all mashups, user profiles and service metadata -intact, but with no activity history. To restore activity logs, shut down the -Mashup Server, connect to the Registry database of the mashup server, located -at MASHUP_HOME//database/WSO2REGISTRY_DB, using a database management tool* -that supports Embedded Derby, and execute the migrated_logs.sql file which -will initialize the logs table and insert the migrated log entries.</p> +<p>2.2 Copy the 'wso2mashup-core-1.5.x-withimport.jar' file from the +'MigrationTool\import' directory to the 'Mashup 1.5 Home\lib' directory.</p> -<p>*You can use the free ij tool that ships with the derby downloadable -distribution available at http://db.apache.org/derby/</p> +<p>2.3 Copy the 'populate.jsp' file from the 'MigrationTool\import' directory +to the 'Mashup 1.5 Home\lib\tomcat\webapps\ROOT' directory.</p> + +<p>2.4 Copy the 'migration.xml' file from the 'MigrationTool\import' +directory to the 'Mashup 1.5 Home\conf' directory.</p> + +<p>2.5.1 Update the <url> parameter in this file with the fully +qualified path to the 'Mashup 1.0 Home\database\WSO2WSAS_DB' directory.'</p> + +<p>2.5 Move the 'server.xml' file out of the 'Mashup 1.5 Home\conf' directory +and copy the 'server.xml' file from the 'MigrationTool\import' directory +there.</p> + +<p>2.6 Copy the user script directories from the 'Mashup 1.0 Home\scripts' +directory to the 'Mashup 1.5 Home\scripts' directory.</p> + +<p>2.6.1 Copy the mashup-metadata.xml file from the 'Mashup 1.0 Home' +directory to the 'Mashup 1.5 Home' directory.</p> + +<p>2.7 Start 1.5.1 Server and access the populate.jsp page (typically at <a +href="https://localhost:7443/populate.jsp";>https://localhost:7443/populate.jsp</a>). +The following page should be displayed.</p> + +<p><img alt="Import Utility" src="images/import_util.png" width="70%"></p> + +<p>2.8 Shut down the 1.5.x server.</p> + +<p>2.9 Delete the files you copied in from the 'MigrationTool' directory and +restore the 'server.xml' file and 'wso2mashup-core-1.5.1.jar' files to the +'conf' and 'lib' directories respectively.</p> + +<p>2.10. Optional: Use a database tool of your choice* to run the +'extracted_logs.sql' file, available in the 'Mashup 1.0 Home' against the +'Mashup 1.5 Home\database\WSO2REGISTRY_DB' database, to restore activity +logs.</p> + +<p>2.11. Start up and provision the 1.5.x server. The data migration is +complete!</p> +<br> + + +<h2>Performing the Migration by Building the Source</h2> + +<p>If required, you can also obtain the source code for the <a +href="https://wso2.org/repos/wso2/people/channa/migration/export/MetadataExtractor.java";>MetadataExtractor</a> +and <a +href="https://wso2.org/repos/wso2/people/channa/migration/import/MigrationInitializer.java";>MigrationInitializer</a> +java classes, which are not included in the MigrationTool.zip file and use +them to build the migration tools from source.</p> + +<h3>MetaData Export</h3> + +<p>User, Mashup and Activity information is extracted saved into the Mashup +Home directory by the 'MetadataExtractor' java class. The source code for +this class should be included in a new 'migration' package of the mashup +server's core module source and built into a mashup-core java archive. The +remaing steps for data extraction are the same.</p> + +<p>The mashup-metadata.xml file contains serialized user information and +metadata for all mashups including tags, comments and ratings entered by all +users.</p> + +<h3>MetaData Import</h3> + +<p>The 'MigrationInitializer' java class re-creates the users registered in +the old instance of the Mashup Server in the new instance and also restores +the user profile and mashup metadata. The source code for this class should +be included in the 1.5.x source and built into a mashup-core java archive. +The remaing steps for data import are the same.</p> </div> +<p>*You can use the free ij tool that ships with the derby downloadable +distribution available at <a +href="http://db.apache.org/derby/";>http://db.apache.org/derby/</a> to execute the +exported SQL statement.</p> + <div id="main-content1"> <p>© 2007-2008 WSO2 Inc.</p> </div> _______________________________________________ Mashup-dev mailing list [email protected] http://mailman.wso2.org/cgi-bin/mailman/listinfo/mashup-dev
