 | Level: Intermediate Nevine Helmy (nhelmy@eg.ibm.com), Software Engineer, IBM
19 Mar 2008 This article shows how to migrate from WebSphere® Commerce
V5.5 on Windows® to WebSphere Commerce V5.6.1 on Linux.
Introduction
This article discusses how to migrate an existing WebSphere Commerce application
across platforms. There are many documents available that describe the process of
migration from version to version or from edition to edition. However, this
article addresses the specific issue of migrating WebSphere Commerce applications
from platform to platform, which is a common request from customers. The example
outlined below shows the steps for migrating from WebSphere Commerce V5.5 on
Windows to WebSphere Commerce V5.6.1 on Linux. If you grasp the general idea, you
can apply the same strategy when migrating other versions and platforms.
Migration plan
The migration guides for WebSphere Commerce describe three migration approaches
that you can use: switchover migration, in-place migration, and co-existence
migration.
In the case of migrating from platform to platform, the only approach to use is
the switchover migration. For this approach, you have a new set of hardware to use
as the production environment for the migrated application. Figure 1 shows the
differences between the three migration approaches.
Figure 1.Migration approaches
Using this switchover migration approach provides the best means to decrease the
production downtime to a minimum. Because you have two complete sets of systems,
you only need to plan the production downtime to be the last step of the migration
process.
After you set up your new hardware and install the new version of WebSphere
Commerce, the next step is to start your WebSphere Commerce application migration.
There are three major milestones in the migration process:
- Instance migration
- Database migration
- Production
This involves remigration of the database to include all the changes that
happened during the migration phase.
Instance migration
Instance migration refers to the process of upgrading the instance
configuration files from their older versions to the newer versions and copying
these new files to the new system, whether it is on the same machine or a
different one. According to the migration guide provided by WebSphere Commerce
(see Resources), the process to migrate the instance
simply involves invoking the WebSphere Commerce Instance Migration (WCIM) script
on the target machine that will generate a zip file containing the files. You need
these files to migrate the existing instance on the source machine.
The next step is to move the zip file to the source machine, unpackage it, and
invoke a script inside it. This script will back up the existing instance and
export it to another zip file, which is finally moved to the target machine to be
migrated to the newer version. In the case of cross-platform migration, however,
things are not that simple. The reason is that the zip file generated on the
target machine in the first step does not contain a script that can run on the
source machine because they are on different operating systems.
To solve this problem, there are several additional steps to perform. Here are
the steps to migrate your instance to a different platform:
- On your target machine, invoke the WCIM script in the same way as described
in the migration guide. To invoke the command, navigate to the bin folder under
the WebSphere Commerce installation directory and type the following
command:
./wcim.sh -component wcim
|
This generates a file called backupwcim.zip under the <WC install
dir> /temp/zip directory.
- Take the generated backupwcim.zip file produced in the above step and copy it
manually to the source machine.
- Unpackage the zip file on the source machine in the <WC install
dir> /temp directory.
- From the above directory, open the file called wcim.sh in a text editor to
view its contents. At the same time, on the source machine, open the file called
wcim.bat from the <WC install dir>/bin directory using a text
editor. You can see what the script file looks like when you run it on the
source machine. Open an empty text file on the source machine that you will use
to copy some of the commands in the other two files. This file is the one you
will eventually run on the source machine to back up the existing instance.
- Go over all the lines in the wcim.bat file from the source machine and
compare it to the one from the target machine. Most likely, you are using the
one on the source machine with some minor changes to incorporate any differences
between the older version of WebSphere Commerce and the newer one that might not
be present in the file from the source machine. Be aware that the WCIM script
file is executed three times:
- The first time is on the target machine to gather all the files needed to
run it on the source machine.
- The second time is when you run it on the source machine to back up the
existing instance to transfer it to the target machine and migrate it.
- Finally, the last execution of the script is on the target machine to
migrate the backed up instance file to the new version. All these steps make
the script file difficult to follow because there are multiple conditions in
the file to execute in different scenarios. Fortunately, there are two
different operating systems on which the script will be executed. You only
need to accommodate the single time that the script is executed on the
Windows source machine. The other two times you run the script, you can use
the shell script that is provided in the Linux installation. What you want
to end up with on the Windows source machine is a script that performs the
following steps:
- Set the server environment by calling some scripts. Take this part
from the Windows file as is, and only make sure that the following
script files are called:
- setenv.bat
- config_env.bat
- setupCmdLine.bat (This file is found in the bin folder under the
WebSphere Application Server installation directory, not under
WebSphere Commerce as the above two files.)
- Set the environment variables CP (classpath) and PATH. The PATH variable
is set to the same value in both files, with the exception that the way the
other variables are referenced on Windows is by using %VARNAME%, and on
Linux by using $VARNAME. Also, note that another difference is the character
separator between values, which is a colon on Linux and a semicolon on
Windows. Accordingly, for this step, you only need to copy the line from the
Linux file and change the way that the variables are referenced and change
the character separator to use the Windows way.
- Find out the type of database used by the server and set the environment
variable DB_TYPE accordingly. Note that the possible values for the DB_TYPE
variable are
db2 or
oracle. You can only have one line setting the
variable to the database type of your migration.
- Set the WCIM_CP variable. The value to set to the variable is the same as
the value set in the Linux file. You only need to copy the value from the
Linux file and change the way the variables are referenced and the character
separator to use the Windows way.
- Set the WCIM_JVM variable. There are two lines in the Linux file setting
the WCIM_JVM variable, depending on the evaluation of a condition. Take the
one that has a comment above it saying “remote backup”. Note that the
comment is not directly above the line, but it is a few lines before it.
Copy the line from the Linux file and change the way that the variables are
referenced and change the character separator to use the Windows way, in the
same way you executed Step 5b above.
- The last step is to execute the com.ibm.commerce.migration.wcim.WCIM
class. Again, there are two lines used to call this class. Use the one
directly following the setting of the WCIM_JVM variable that you used in the
above step.
- Now that the tough part is over, you can place the new text file in which you
accumulated the commands you want to be called by the script file. This is in
the same place where you unpackaged the backupwcim.zip file in Step 3 above.
Place it in the bin directory where the wcim.sh file was found. Name this new
file
wcim.bat.
- The rest of the steps follow the steps in the migration guide. We will list
them here. On the source machine, execute the new wcim.bat script found under
<WC Install root>\temp\bin:
wcim.bat -component wc -from 55 -backup remote -instanceName <your instance name>
|
- After the wcim script runs, you are prompted to enter information about your
source installation. After you enter them successfully, a file called
instance-backup.zip is generated under <WC Install root>\temp.
Copy this file to the target machine under <WC Install root>\temp
and unpackage it on the target machine.
- Run the wcim.sh file on the target machine from the <WC Install
root>\bin directory:
./wcim.sh -component wc -from 55 -migration remote -instanceName <your instance name>
|
- Again, running the script prompts you to enter information about the new
WebSphere Commerce installation. After you enter all of them successfully, then
you have migrated your instance. The final check is to verify that WCIM ran
successfully by checking the log files under <WC Install
root>/temp/logs on the target machine.
Here is a summary of the steps to migrate your WebSphere Commerce instance.
Figure 2 shows an overview of the steps.
Figure 2. Instance migration steps
Database migration
Database migration involves two steps. The first is to copy your old
database to the new system where you host the updated production environment.
Then, you can run the WebSphere Commerce-supplied scripts to migrate the database
to the new version. Unfortunately, in the case of migrating across platforms,
things are not as straightforward as they appear.
To perform the first step, back up the old database and restore it on the new
system. However, back up and restore is not supported across different operating
systems. There are two alternatives to back up and restore in this case. The first
is to use the db2move utility that comes with DB2® to accomplish the move. The
second is to use the EXPORT command followed by the IMPORT command.
In our case, it is simpler to use the db2move because it can move the whole
database in one execution, instead of using the EXPORT and IMPORT commands to
export and import one table at a time. In normal conditions, db2move is sufficient
to perform the move. The only drawback is that in earlier versions, it does not
always preserve encoding of the data. Depending on the exact version of DB2 you
are using on the source machine, if your database contains UTF data characters,
they might not be readable after the move is done.
Accordingly, you need to either have all the SQL you used to insert the UTF data
into the database before to reapply it to the new database on the new system after
the move and in case you find them unreadable. Or, for the tables that have UTF
data characters in them, you perform an EXPORT followed by an IMPORT command.
The steps to perform the move are:
- Back up your current database so that you can use the new copy in the move
and leave the other database running to minimize production downtime.
- Restore the new copy of the database on the new machine.
- Invoke the db2move utility with the EXPORT option on the new database copy
you restored previously. The exact syntax to invoke the utility is described
below. The output of this invocation is located in the same folder you were
invoking the db2move from. There is a .ixf file and a .msg file for each table
in the database. These are named tab1, tab2, and so on. There is also a common
file named EXPORT.out that stores the output of the utility itself.
- Invoke the db2move utility with the IMPORT option on the new machine using
the files you moved in the previous step. The syntax to invoke the db2move
utility is simple:
db2move <database name> EXPORT
db2move <database name> IMPORT
|
After you import the files to the new machine and ensure that all the characters
are readable (Step 4 above), you are ready to go to the next step, which is
simpler than the first. This is when you need to run the WebSphere
Commerce-supplied script to upgrade the database schema to the level supported by
WebSphere Commerce V5.6. To do this, you only need to invoke the following command
on the target machine from the <WC Install root>/bin directory:
./migratedb.sh -dbtype db2 -dbname <your db name> -dbuser <db user> -dbpass
<db pass> -from 55 -instanceName <instance name>
|
For more information, see the appropriate migration guide.
Moving to production
A tricky part of any migration project is the expected production downtime, or
the time when all operations are stopped while the old system is disabled and the
new system takes over. In cross-platform migration, production downtime is not
long because there are two sets of hardware so you can keep the old production
system running until the end and only stop operations for a relatively small
amount of time. The actual time that the site will need to be down also depends on
whether or not clustering is involved. If the site is clustered, the production
downtime is further reduced.
All the above steps were performed while the old production system was up and
running. This means that the database was actively storing new data. To start
using the new system, you need a plan that ensures all the new data stored during
the migration phases outlined above needs to be moved to the new system again.
However, this time while the site is down, make sure that no more new data is
stored. Assuming that the new site was tested thoroughly and all problems during
the migration process were fixed, the next logical step is to use the new hardware
instead of the old. To move the live site to the new hardware, you cannot
start the new server and shut down the old one.
Here is a sample plan for the production downtime, assuming no clustering:
- Make sure that any configuration or properties files used to store file
system information that is used by your customized code are updated to use the
new machines.
- Make sure that the host name and IP address of the live site is correctly set
in the new machines.
- Shut down the old production system. Note that at this point the site remains
down until the remigration of the database is carried out in the next step.
- Remigrate the old database. This is done to capture the transactions that
took place while you were migrating the system. It has to be done when the old
system is completely down so that no further transactions will take place at the
same time. You can follow the same steps outlined above for migrating the
database.
- Start the new production system.
Conclusion
Migrating a WebSphere Commerce application across platforms can be challenging.
However, by planning the migration and following a logical path, you find that it
is possible. This article focused on migrating from WebSphere Commerce V5.5 to
V5.6.1. If you need to migrate to other versions of WebSphere Commerce, you can
use the same overall steps by changing some of the details that are relevant to
the specific version you are migrating from or to.
Resources
About the author
Rate this page
| |
