Menu
▾
▴
[jboss-cvs] jboss-portal-docs/referenceGuide/en/modules ...
|
From: Roy R. <ru...@jb...> - 2006-07-10 17:30:19
|
User: russo
Date: 06/07/10 13:30:17
Modified: referenceGuide/en/modules migration.xml
Log:
JBPORTAL-933 - done
Revision Changes Path
1.13 +247 -188 jboss-portal-docs/referenceGuide/en/modules/migration.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: migration.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-portal-docs/referenceGuide/en/modules/migration.xml,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -b -r1.12 -r1.13
--- migration.xml 6 Jul 2006 20:46:35 -0000 1.12
+++ migration.xml 10 Jul 2006 17:30:17 -0000 1.13
@@ -12,61 +12,64 @@
</author>
</chapterinfo>
<title>Upgrading 2.2 - 2.4</title>
- <warning>The migration application is not complete, as of the time of this document writing. It is suggested, users
- wait before attempting to migrate their data using this application.</warning>
- <para>This chapter addresses migration issues from version 2.2 to 2.4 of JBoss Portal. TODO...</para>
+ <para>This chapter addresses migration issues from version 2.2 to 2.4 of JBoss Portal.</para>
<sect1 id="migrating_database">
- <title>Migrating Database</title>
+ <title>Migrating the Database</title>
<para>JBoss Portal 2.4 comes with dedicated web application for database migration.
- This tool is designed to provide maximum ease of use to make migration process fast and pleasant.
+ This application will migrate your existing JBoss Portal 2.2 database data to a new one, for use with JBoss
+ Portal 2.4.
</para>
- <para>The migration process should be performed
+ <warning>This migration process should be performed
<emphasis role="bold">before</emphasis>
- JBoss Portal 2.4 deployment
- </para>
+ JBoss Portal 2.4 deployment.
+ <emphasis role="bold">Follow the exact steps below, in order, or ugly scary things may happen!</emphasis>
+ </warning>
<sect2 id="migration_preparations">
- <title>Preparing Database</title>
- <para>Migration process occures between two databases:</para>
+ <title>Database Requirements/Preparation</title>
+ <para>You will need two database instances for this migration process to function:</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Source JBP 2.2 database</emphasis>
- from which we migrate portal data
+ from which we migrate portal data. (You should already have this!)
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Destination JBP 2.4 database</emphasis>
- to which we migrate portal data
+ to which we migrate portal data.
</para>
</listitem>
</itemizedlist>
- <para>Before you begin the process you must create separate database to which the data
- will be migrated. Note that Migration Application performs Hibernate SchemaExport which
- drops and recreates tables - It is alway recommended that you backup your database before start!!!</para>
- <para>For scope of examples presented in this chapter lets assume we use MySQL database and have:</para>
+ <para>Before you begin the process you must create a separate database to which the data
+ will be migrated. Note that the Migration Application performs a Hibernate SchemaExport which
+ drops and recreates tables - It is recommended that you backup your database before starting!</para>
+ <para>For our example, we have two databases... the existing one for JBoss Portal 2.2, and the new (empty) one
+ for JBoss Portal 2.4:
<itemizedlist>
<listitem>
<para>
- JBoss Portal 2.2 database called
+ JBoss Portal 2.2 DB:
<emphasis role="bold">jbossportal22</emphasis>
- which contains our production data
</para>
</listitem>
<listitem>
<para>
- Newly created database called
+ JBoss Portal 2.4 DB:
<emphasis role="bold">jbossportal24</emphasis>
- to which we want to migrate our data and deploy JBoss Portal 2.4 on it.
</para>
</listitem>
</itemizedlist>
+ We will use the above database naming, as examples in the next chapter on configuring the datasource.
+ </para>
</sect2>
<sect2 id="datasource_prepare">
- <title>Preparing Datasources</title>
- <para>To point Migration Application from and to where it should migrate data we use
- JBoss Application Server datasource files.</para>
- <para>For your normal JBoss Portal 2.2 deployment you probably have
+ <title>DataSource Requirements/Preparation</title>
+ <para>The Migration Application will need access to both databases, while its running. For this reason, we need
+ to make available both JBoss Application Server datasource files.</para>
+ <orderedlist>
+ <listitem>
+ <para>You should have an existing JBoss Portal 2.2 datasource,
<emphasis role="bold">portal-ds.xml</emphasis>
or
<emphasis role="bold">portal-*-ds.xml</emphasis>
@@ -86,8 +89,10 @@
</datasources>
]]>
</programlisting>
- <para>You need to create a second datasource to be able to point Migration App. to the
- destination database. In our case we can create
+ </listitem>
+ <listitem>
+ <para>Now, you will need to create a second datasource for the destination database. In our example we
+ will create,
<emphasis role="bold">portal-migration-ds.xml</emphasis>
file that looks like this:
</para>
@@ -105,28 +110,18 @@
</datasources>
]]>
</programlisting>
- <para>Both files should be placed in
- <emphasis role="bold">server/default/deploy</emphasis>
- directory of the application server on which you plan to deploy migration application.
- </para>
+ </listitem>
+ </orderedlist>
</sect2>
<sect2 id="getting_tool">
- <title>Obtaining Migration Application</title>
- <para>Portal Migration Application can be obtained either as ready to deploy web application or builded from
- source.</para>
+ <title>Obtaining the Migration Application</title>
+ <para>The JBoss Portal Migration Application can be obtained either as a ready to deploy web application or in source form.</para>
<sect3 id="getting_app_binary">
<title>Downloading binary</title>
- <para>You can find prepared binaries at:</para>
+ <para>You can find a prepared binary at:</para>
<itemizedlist>
<listitem>
<para>
- <ulink url="http://www.portletswap.com">PortletSwap</ulink>
- - the place you can find many
- ready portlets
- </para>
- </listitem>
- <listitem>
- <para>
<ulink url="http://labs.jboss.com/portal/jbossportal/download">Download</ulink>
section of JBoss Portal project page
</para>
@@ -175,7 +170,7 @@
<para>Deployable web application archive can be found at
<emphasis role="bold">jboss-portal-2.4/migration/output/lib/portal-migration.war</emphasis>
</para>
- <para>You can also deploy it automaticly by executing:</para>
+ <para>You can also deploy it automatically by executing:</para>
<programlisting>
<![CDATA[
cd jboss-portal-2.4
@@ -185,18 +180,49 @@
</programlisting>
</sect3>
</sect2>
+ <sect2 id="deploying_migration">
+ <title>Deploying the Migration Application</title>
+ <para>
+ The steps below will guide you through deploying and running the migration application:
+ <orderedlist>
+ <listitem>
+ <para>Shut down JBoss Application Server</para>
+ </listitem>
+ <listitem>
+ <para>Undeploy/Remove JBoss Portal 2.2 (JBOSS_HOME/server/default/deploy/jboss-portal.sar)</para>
+ </listitem>
+ <listitem>
+ <para>Delete
+ <emphasis>JBOSS_HOME/server/default/data/portal/cms</emphasis>
+ (This directory will be created for you, once again, when JBoss Portal 2.4 initializes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Deploy the
+ <emphasis role="bold">two</emphasis>
+ necessary datasource descriptors, from
+ <xref linkend="datasource_prepare"/> to JBOSS_HOME/server/default/deploy/*
+ </para>
+ </listitem>
+ <listitem>
+ <para>Deploy the Migration Application, you obtained from
+ <xref linkend="getting_tool"/> to JBOSS_HOME/server/default/deploy/portal-migration.war
+ </para>
+ </listitem>
+ <listitem>
+ <para>Start JBoss Application Server</para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </sect2>
<sect2 id="running_migration">
- <title>Running Migration Application</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" valign="middle" fileref="images/migration/migration_app_1.jpg"/>
- </imageobject>
- </mediaobject>
+ <title>Running the Migration Application</title>
+ <orderedlist>
+ <listitem>
<para>After deploying Migration Application you can access it at
- <emphasis role="bold">http://localhost:8080/portal-migration</emphasis>
+ <ulink url="http://localhost:8080/portal-migration">http://localhost:8080/portal-migration</ulink>
. It is
password protected so you need to specify:
- </para>
<itemizedlist>
<listitem>
<para>
@@ -211,122 +237,158 @@
</para>
</listitem>
</itemizedlist>
- <para>Password can be changed in
+ <note>The Password can be changed in
<emphasis role="bold">portal-migration.war/WEB-INF/classes/users.properties</emphasis>
- file. Remember to always change the password to less trivial one or undeploy the war file after migration
+ file. Remember to always change the password to a less trivial one, or undeploy the war file after
+ the
+ migration
process.
- Otherwise someone can later have unprotected access to application that can wipe out your database tables...
+ </note>
</para>
- <para>If you logged in successfully you should access this page:</para>
+ </listitem>
+ <listitem>
+ <para>If you logged in successfully you should access this page:
<mediaobject>
<imageobject>
<imagedata align="center" valign="middle" fileref="images/migration/migration_app_3.jpg"/>
</imageobject>
</mediaobject>
+ </para>
+ </listitem>
+ <listitem>
<para>At
<emphasis role="bold">Step 2: 2.4 Database Connectivity Check</emphasis>
you need to provide datasouce name
that points to JBoss Portal 2.4 database (the destination one)
- </para>
+
<mediaobject>
<imageobject>
<imagedata align="center" valign="middle" fileref="images/migration/migration_app_4.jpg"/>
</imageobject>
</mediaobject>
+ </para>
+ </listitem>
+ <listitem>
<para>
<emphasis role="bold">Step 3: Create Tables</emphasis>
- </para>
+
<mediaobject>
<imageobject>
<imagedata align="center" valign="middle" fileref="images/migration/migration_app_5.jpg"/>
</imageobject>
</mediaobject>
+ </para>
+ </listitem>
+ <listitem>
<para>If both connections were valid and database schema was created successfully you can
- follow with the migration process. It is separated into following parts:</para>
+ follow with the migration process. It is separated into following parts:
<itemizedlist>
<listitem>
<para>
- <emphasis role="bold">CMD Data Migration</emphasis>
- - migrates portal builtin CMS tables content
- </para>
+ <emphasis role="bold">CMS Data Migration</emphasis>
+ - migrates portal CMS tables content
+
<imageobject>
<imagedata align="center" valign="middle" fileref="images/migration/migration_app_6.jpg"/>
</imageobject>
+ </para>
</listitem>
<listitem>
<para>
<emphasis role="bold">User/Role Data Migrate</emphasis>
- migrates portal user, roles and
relations beetween them
- </para>
+
<imageobject>
<imagedata align="center" valign="middle" fileref="images/migration/migration_app_7.jpg"/>
</imageobject>
+ </para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Portal Object Data Migrate</emphasis>
- migrates
whole portal objects structure. This means nodes like portals, pages and windows.
- </para>
+
<imageobject>
<imagedata align="center" valign="middle" fileref="images/migration/migration_app_8.jpg"/>
</imageobject>
+ </para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Portal Portlet Instance Data Migrate</emphasis>
- migrates
all portlet instances presented in portal. For each portlet instance its preferences are also
- persisted. Next all already migrated users are iterated and user preferences related to portlet
+ persisted. Next, all already migrated users are iterated and user preferences related to
+ portlet
instance are migrated
- </para>
+
<imageobject>
<imagedata align="center" valign="middle" fileref="images/migration/migration_app_9.jpg"/>
</imageobject>
+ </para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Portal Security Data Migrate</emphasis>
- migrates security data for portal
objects and portlet instances.
- </para>
+
<imageobject>
- <imagedata align="center" valign="middle" fileref="images/migration/migration_app_10.jpg"/>
+ <imagedata align="center" valign="middle"
+ fileref="images/migration/migration_app_10.jpg"/>
</imageobject>
+ </para>
</listitem>
</itemizedlist>
- <para>Which all should lead to successfull end :)</para>
+ </para>
+ <para>Which should lead to a successfull end :)
<imageobject>
<imagedata align="center" valign="middle" fileref="images/migration/migration_app_11.jpg"/>
</imageobject>
- </sect2>
- <sect2 id="migration_fail">
- <title>Migration failed...</title>
- <para>If any error occure during migration process you will be provided
- with specific information and enabled to retry that step</para>
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ <note>If any error occured during the migration process you will be provided
+ with specific information and asked to retry that step
<imageobject>
<imagedata align="center" valign="middle" fileref="images/migration/migration_app_9-fail.jpg"/>
</imageobject>
<imageobject>
<imagedata align="center" valign="middle" fileref="images/migration/migration_app_10-fail.jpg"/>
</imageobject>
- <para>Always check Application Server console output or logs after migration to track possible fail
- cause.</para>
+ Always check the Application Server console output or logs after migration to track possible
+ errors.
+ </note>
+ </para>
</sect2>
<sect2 id="migration_final">
<title>Final steps</title>
- <para>After running Migration Application you need some additional steps to
- finish migration process:</para>
- <itemizedlist>
+ <para>After running the Migration Application you need to perform some additional steps to
+ finish the process:</para>
+ <orderedlist>
+ <listitem>
+ <para>Shutdown JBoss Application Server</para>
+ </listitem>
<listitem>
<para>
- Undeploy JBoss Portal 2.2
+ Undeploy JBoss Portal 2.2 (jboss-portal.sar)
+ </para>
+ </listitem>
+ <listitem>
+ <para>Undeploy the JBoss Portal 2.2 deployment descriptor</para>
+ </listitem>
+ <listitem>
+ <para>Delete
+ <emphasis>JBOSS_HOME/server/default/data/portal/cms</emphasis>
+ (This directory will be created for you, once again, when JBoss Portal 2.4 initializes.
</para>
</listitem>
<listitem>
<para>
- Edit you datasource files and set up the one pointing to newly migrated 2.4 database to have:
+ Edit your 2.4 datasource file and modify the jndi name:
<emphasis role="bold">
<![CDATA[<jndi-name>PortalDS</jndi-name>]]>
</emphasis>
@@ -334,16 +396,13 @@
</listitem>
<listitem>
<para>
- Deploy JBoss Portal 2.4
+ Deploy JBoss Portal 2.4.
</para>
</listitem>
- </itemizedlist>
- </sect2>
- <sect2 id="possible_problems">
- <title>Possible Issues</title>
- <para>Migration Application uses JBoss Portal model classes and is based on
- hibernate. Every database supported by hibernate should be valid for migration.</para>
- <para>TODO...</para>
+ <listitem>
+ <para>Start JBoss Application Server</para>
+ </listitem>
+ </orderedlist>
</sect2>
</sect1>
<sect1 id="descriptors_migration">
|
