[DevWorks] Migrating from Apache Tomcat to the WebSphere Application Server Liberty Profile

Migrating from Apache Tomcat to the WebSphere Application Server Liberty Profile

Introduction
Apache Tomcat is an HTTP server and servlet container that is popular for simple web applications and for applications that use frameworks that do not require a full Java™ EE server. However, users often find the initial simpilicity of Apache Tomcat can become complex and impractical the more demands are placed on it.
For example, perhaps the footprint of your Apache Tomcat installation has grown too large, as you have needed to add third party libraries to provide required functionality. Or, perhaps your server startup time has become an issue, as any configuration change to the server.xml file requires a restart of the Apache Tomcat server. Or, maybe integrating and maintaining third party libraries has become too time consuming.
Any one of these conditions is reason enough to consider migrating your Apache Tomcat applications and their configuration information to the IBM WebSphere Application Server V8.5.5 Liberty Profile. The Liberty profile provides a lightweight and simple to use application server with a small footprint and a quick server startup time. It also includes many Java EE features that are not part of Apache Tomcat, reducing the need to integrate and maintain third-party libraries.
With the Liberty profile:

• Users configure the components needed by their applications, keeping the server footprint small and the server startup time fast.
• Configuration changes do not require a restart of the server. They are picked up automatically.
• WebSphere Application Server Developer Tools for Eclipse make developing, testing, and publishing web applications on the Liberty profile easy.
• Configuration is through a simple XML file. WebSphere Application Server Developer Tools for Eclipse provides an intuitive user interface to view and modify that configuration.

Find out more about the WebSphere Application Server V8.5.5 Liberty Profile in the Information Center and in the WASdev community.

This article provides instructions for migrating your applications and their configuration information from Apache Tomcat to the WebSphere Application Server V8.5.5 Liberty Profile.
Before migrating the configuration, however, you should first migrate your applications in order to ensure optimal compatibility and performance with WebSphere Application Server V8.5. To assist with that migration, the Application Migration Tool - Apache Tomcat to WebSphere is available in the IBM WebSphere Application Server Migration Toolkit for scanning the application code to detect needed updates and provide quick fixes where possible. A new configuration migration tool, Tomcat Config Migration, available as a Tech Preview from the WASdev development blog, can then migrate a subset of the server and application configuration to the Liberty profile. When used together, these migration tools provide a reliable and easy way to migrate from Apache Tomcat to the Liberty profile.
Prerequisites
This article assumes you already have an application configured for Apache Tomcat that you wish to migrate and publish on the WebSphere Application Server Liberty profile. For illustrative purposes, this article references a published sample application (IBM Redbooks Publications Sample Application) included in an IBM Redbook publication. More information about this application, including download instructions, can be found in Chapter 9.4 of the WebSphere Application Server V8.5 Migration Guide. The remainder of this article refers to it as the sample application.
To follow the instructions in this article, you will need to have the software listed here downloaded, properly installed, and operational:

• Eclipse 4.2.2 for Java EE Developers (Juno SR2)
• IBM WebSphere Application Server V8.5.5 Liberty Profile
• IBM WebSphere Application Server Developer Tools for Eclipse V8.5.5
• Application Migration Tool – Apache Tomcat to WebSphere V3.5.1
• Tomcat Config Migration Tech Preview V3.5.1

Back to top

1. Migrate the application
The first step is to migrate the application itself using the Application Migration Tool – Apache Tomcat to WebSphere. If your application is not yet in your Eclipse workspace, follow these steps to import it:

1. In Eclipse, select File > Import...
2. Select Web > WAR file.
3. Click Next.
4. Click Browse to navigate to the WAR file.
5. Set the Target runtime to WebSphere Application Server V8.5 Liberty Profile.
6. Click Next, then Finish.

Now you can configure and run the Application Migration Tool. Follow the detailed instructions found in Chapter 9.4.5 of the WebSphere Application Server V8.5 Migration Guide.
After the application is migrated, you can begin migrating the configuration.

Back to top

2. Migrate the Apache Tomcat server configuration
In Apache Tomcat, certain configuration elements required by an application are located in the server.xml, context.xml, or tomcat-users.xml files, all of which are located in the Apache Tomcat conf directory. Without the migration tool, you would have to migrate that configuration information manually to the Liberty profile server configuration.
The following server configuration information is migrated, when present:

• Resources located in conf/server.xml and conf/context.xml for IBM DB2®, Apache Derby, Apache ActiveMQ, and IBM WebSphere MQ.
• HTTP connectors located in conf/server.xml.
• Session managers located in conf/context.xml.
• Users and roles located in conf/tomcat-users.xml.

Create a Liberty profile server for the migration, if you have not already done so:

1. In Eclipse, select File > New > Other.
2. Select Server > Server and click Next.
3. Choose the server type: WebSphere Application Server V8.5 Liberty Profile.
4. Set the server name: defaultServer.
5. Click Next.
6. Under the installation folder, enter the location where you installed the Liberty profile runtime environment.
7. Click Finish.

Your workspace should now include an instance of a Liberty profile server (Figure 1).

Figure 1. Eclipse workspace with Liberty profile server

Now you can migrate the Apache Tomcat server configuration to the Liberty profile server:

8. Select Run > Tomcat Configuration Migration... (Alternatively, if the Apache Tomcat server is defined in Eclipse, you can right click on the Apache Tomcat server in either the Project Explorer or the Servers pane and select Migrate Tomcat Configuration..., and then continue with step j, below.)
9. Browse to the location of the Apache Tomcat server installation. Select the file folder, and click OK.
10. Select the Liberty profile server that you are migrating to, and click OK.
11. Click OK to close the completion dialog.

The Liberty profile server now contains a new migratedConfig directory with the migrated Apache Tomcat server configuration as a result (Figure 2).

Figure 2. Liberty profile server after migrating Apache Tomcat server configuration

The structure of the migrated files within the migratedConfig directory closely follows that of the Apache Tomcat server configuration:

• The server.xml file contains a subset of the configuration migrated from the conf/server.xml file.
• The context.xml file contains a subset of the configuration migrated from the conf/context.xml file.
• The users-and-roles.xml file contains the users and roles migrated from the conf/tomcat-users.xml file.

There is also a log file (configMigration.log), a copy of the original Liberty server.xml file (server.xml.orginal), and a generated configuration file (server-updates-for-config.xml) that includes the server.xml, context.xml, and users-and-roles.xml files. The server-updates-for-config.xml file is included in the Liberty server.xml file. This is how the migrated configuration is added to a Liberty server configuration.
Let us look at the server configuration required for the sample application as a specific migration example. The sample application requires a global data source which must be configured in the Apache Tomcat server.xml as a global naming resource, and an HTTP port to allow access to the application (Listing 1).

Listing 1. Example Apache Tomcat server.xml configuration

… <Resource auth="Container" description="Derby database redbook sample" driverClassName="org.apache.derby.jdbc.EmbeddedDriver" maxActive="100" maxIdle="30" maxWait="10000" name="jdbc/globalStyleSettings" type="javax.sql.DataSource" url="jdbc:derby:/temp/TomcatDatabases/styles;create=true" username="" password=""/> … <Connector port="8080" protocol="HTTP/1.1" maxThreads="150" socket.soReuseAddress="true" connectionTimeout="20000" redirectPort="8443"/> …

After migrating the server configuration shown in Listing 1, the migratedConfig/server.xml file contains an httpEndpoint and dataSource (Listing 2).

Listing 2. Example of migrated server.xml configuration

… <httpEndpoint host="localhost" httpPort="8080" httpsPort="8443" id="httpConnector-AbT0"> <httpOptions maxKeepAliveRequests="150" persistTimeout="20s"/> <tcpOptions soReuseAddr="true"/> </httpEndpoint> … <dataSource id="globalStyleSettingsDSDerby" jndiName="jdbc/globalStyleSettings"> <jdbcDriver> <library> <fileset dir="${shared.resource.dir}" includes="derby.jar"/> </library> </jdbcDriver> <properties.derby.embedded createDatabase="create" databaseName="/temp/TomcatDatabases/styles"/> <connectionManager connectionTimeout="10s" maxPoolSize="100" minPoolSize="30"/> </dataSource> …

The sample application also requires a “test” user and “Test” role, which are defined in the tomcat-users.xml file in the conf directory (Listing 3).

Listing 3. Example of Apache Tomcat tomcat-users.xml configuration

… <role rolename="Test"/> <user username="test" password="test" roles="Test"/> …

After migrating the server configuration shown in Listing 3, the migratedConfig/users-and-roles.xml file contains a user and a group with a member (Listing 4).

Listing 4. Example of migrated tomcat-users.xml configuration

… <user name="test" password="{hash}ATAAAAAIy/2zRjmVAXtAAAAAIF85OBJn2R/DyAPJi8suNDd/PV2liDswtmd2qgfvFQiZ"/> <group name="Test"> <member name="test"/> </group> …

In the next section, you will migrate the application configuration.

Back to top

3. Migrate the application configuration
Certain configuration data required by an application can be located in the application’s META-INF/context.xml or WEB-INF/web.xml files. Without the migration tool, that configuration must be migrated manually to the Liberty profile server configuration.
The following configuration information is migrated, when present:

• Resources located in META-INF/context.xml for IBM DB2, Apache Derby, Apache ActiveMQ, and IBM WebSphere MQ.
• Application security constraints located in WEB-INF/web.xml.

If the application depends on any IBM DB2 or Apache Derby resources, you must first copy the relevant database JAR files from the Apache Tomcat installation to the ${shared.resources.dir} of the Liberty profile installation:

1. Copy derby.jar from the lib directory of the Apache Tomcat installation to the usr/shared/resources directory of the Liberty profile installation.
2. Copy db2jcc4.jar and db2jcc_license_cu.jar from the lib directory of the Apache Tomcat installation to the usr/shared/resources directory of the Liberty profile installation.

With the sample application, the Apache Derby database is required. Therefore, the derby.jar file needs to be copied as described above (step a). If you currently do not have a copy of derby.jar in the lib directory of the Apache Tomcat installation, you can download the required Apache Derby files. (The specific file to download for Version 10.8.2.2, for example, is "db-derby-10.8.2.2-bin.zip.")

Figure 3. Location of database resources in the Liberty profile installation

Now you can migrate the application configuration:

3. Right-click the project for your application and select Migrate Tomcat Configuration...
4. Select the Liberty profile server that you are migrating to, and click OK.
5. Click OK to close the completion dialog.

As a result, the Liberty profile server contains a new subdirectory with the application name under the migratedConfig directory. For the sample application, a newly created RedbookLibrary directory contains the migrated application configuration (Figure 4).

Figure 4. Liberty profile server after migrating the application configuration

The migrated files within the RedbookLibrary directory closely map to those of the application:

• The application-config-context.xml file contains a subset of configuration migrated from the META-INF/context.xml file.
• The application-config-web.xml file contains a subset of configuration migrated from the WEB-INF/web.xml file.

There is also a log file (configMigration.log), a copy of the original Liberty server.xml file (server.xml.orginal), and a generated configuration file (server-updates-for-application.xml) that includes the application-config-context.xml and application-config-web.xml files. The server-updates-for-application.xml file is included in the Liberty server.xml. This is how the migrated configuration is added to the Liberty server configuration.
Let us look at the application configuration required for the sample application. The sample application requires two local data sources which are configured in the META-INF/context.xml file (Listing 5), and a security role and security constraint in the WEB-INF/web.xml file (Listing 6).

Listing 5. Example of configuration in META-INF/context.xml

… <Resource auth="Container" description="Derby database Demo Tomcat Book App" driverClassName="org.apache.derby.jdbc.EmbeddedDriver" maxActive="100" maxIdle="30" maxWait="10000" name="DefaultDatasource" type="javax.sql.DataSource" url="jdbc:derby:/temp/TomcatDatabases/books;create=true" username="" password="" /> <Resource auth="Container" description="Derby database for members" driverClassName="org.apache.derby.jdbc.EmbeddedDriver" maxActive="100" maxIdle="30" maxWait="10000" name="jdbc/Members" type="javax.sql.DataSource" url="jdbc:derby:/temp/TomcatDatabases/members;create=true" username="" password=""/> …

Listing 6. Example of configuration in WEB-INF/web.xml

… <security-constraint> <web-resource-collection> <web-resource-name>TestRole</web-resource-name> <url-pattern>/test/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>Test</role-name> </auth-constraint> </security-constraint> … <security-role> <role-name>Test</role-name> </security-role> …

After migrating the application configuration shown in Listing 5, the migratedConfig/RedbookLibrary directory contains an application-config-context.xml file with two dataSources configured (Listing 7).

Listing 7. Example of migrated application configuration from context.xml

… <dataSource id="DefaultDatasourceRedbookLibraryDSDerby" jndiName="DefaultDatasource"> <jdbcDriver> <library> <fileset dir="${shared.resource.dir}" includes="derby.jar"/> </library> </jdbcDriver> <properties.derby.embedded createDatabase="create" databaseName="/temp/TomcatDatabases/books"/> <connectionManager minPoolSize="30" connectionTimeout="10s" maxPoolSize="100"/> </dataSource> <dataSource id="MembersRedbookLibraryDSDerby" jndiName="jdbc/Members"> <jdbcDriver> <library> <fileset dir="${shared.resource.dir}" includes="derby.jar"/> </library> </jdbcDriver> <properties.derby.embedded createDatabase="create" databaseName="/temp/TomcatDatabases/members"/> <connectionManager minPoolSize="30" connectionTimeout="10s" maxPoolSize="100"/> </dataSource> …

After migrating the application configuration shown in Listing 6, the migratedConfig/RedbookLibrary directory contains an application-config-web.xml file with an application and security role configured (Listing 8).

Listing 8. Example of migrated application configuration from web.xml

… <application id="RedbookLibrary" location="RedbookLibrary.war" name="RedbookLibrary" type="war"> <application-bnd> <security-role name="Test"> <user name="test"/> </security-role> </application-bnd> </application> …

To determine which users to add to the “Test” security-role on the application, the users-and-roles.xml file in the migratedConfig directory was examined to find which users were members of the group “Test”. This technique enabled this configuration to be automatically generated as part of the migration, instead of having to manually publish the application and configure the security-role afterwards.
For the sample application, using the migration tool for the server configuration and application configuration eliminated the need to perform the manual steps that are documented in Chapters 9.4.6 and 9.4.7 of the WebSphere Application Server V8.5 Migration Guide.
Next, you will run the migrated application on the Liberty profile server.

Back to top

4. Run the application on the Liberty profile
As a result of the migration of the application configuration, the application is now published on the Liberty profile server. Simply start the server and access the application:

1. In Eclipse, right-click the Liberty profile server and select Start.
2. Click on the application URL in the Console pane, or enter the application URL in the web browser of your choice. For the sample application, the URL is http://localhost:8080/RedbookLibrary/.

Figure 5. Run the application in Eclipse by clicking the application URL in the Console pane

To test the sample application:

3. Click Build The Databases.
4. When prompted for user name and password, enter test for both.
5. Go back to the main page and click Populate the Database with test data.
6. Go back to the main page and log in with User ID of user1 and a Password of password1.

Notice that the migrated users and roles along with the migrated application security constraint are utilized in step d above, which requires a user that is a member of the “Test” role to log in to create the test data.
For more information on testing the sample application in the Liberty profile server, see Chapter 9.4.8 of the WebSphere Application Server V8.5 Migration Guide.

Back to top

Conclusion
This article described how to migrate an application and its configuration from Apache Tomcat to the WebSphere Application Server Liberty Profile using the Application Migration Tool – Apache Tomcat to WebSphere (for the application migration) and the Tomcat Config Migration Tech Preview (for the configuration migration). Simplifying the process by using these utilities makes migrating to the Liberty profile server easier and more reliable than ever.

Resources
Learn

• Redbook: WebSphere Application Server V8.5 Migration Guide
  
• IBM developerWorks WebSphere
  

Get products and technologies

• Visit WASdev.net to download these products and tools:
  • WebSphere Application Server Liberty Profile
  • WebSphere Application Server Developer Tools for Eclipse
  • WebSphere Application Server Migration Tools
  • Tomcat Config Migration
• IBM WebSphere Application Server Migration Toolkit
  

Discuss
Application Migration Tool Forum